Table of Contents:
Table of Contents minLevel 2
Intro
| Info |
|---|
| The Mailing API gives you access to all your mailing campaigns in your account. |
Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used.
Methods Summary
GET /api/mailings/<Campaign ID>
Description
This method fetches a single mailing, including email messages, segments and distribution.
...
Campaign Status Codes
| Status | Code |
|---|---|
| NEW | 60001 |
| SCHEDULED | 60002 |
| IN_PROGRESS | 60003 |
| COMPLETED | 60004 |
| ERROR | 60005 |
| CANCELLED | 60006 |
| DELETED | 60007 |
| COMPLETED_WITH_ERRORS | 60008 |
| ON_HOLD | 60009 |
| STOPPED | 60010 |
GET /api/mailings
Description
This method gives collection of campaigns in response.
...
Optional int
limit
Optional int
POST /api/mailings
Description
This method creates a new mailing campaign. If "schedule_date" is provided (as Unix timestamp), campaign will be scheduled. Otherwise if none provided it will launch immediately.
...
| Code Block |
|---|
{
"name": "My new campaign",
"description": "Handle with care",
"email_message": [ 27 ],
"segments": [ 1429 ],
"distribution": [
{
"esp_connection_id": 12345 ,
"percent": 100
}
]
} |
Example - Regular campaign request sample with ESP connection/domain distribution
IMPORTANT - In case of domain distribution you must specify the default distribution for the rest of the domains as well.
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{
"name": "New campaign with domain distribution",
"description": "Handle with care",
"email_message": [ 27 ],
"segments": [ 1429 ],
"distribution": [
{
"esp_connection_id": 12345,
"percent": 100,
"domain": "gmail.com"
},
{
"esp_connection_id": 67890,
"percent": 100,
"domain": "default"
}
]
} |
Example - Regular campaign request sample with ESP connection / segments distribution
IMPORTANT - The only allowed segment ids in this distribution are the ones provided in the segments array.
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{
"name": "New campaign with segments distribution",
"description": "Handle with care",
"email_message": [ 27 ],
"segments": [ 1429, 1428 ],
"distribution": [
{
"esp_connection_id": 12345,
"percent": 100,
"segment_id": 1429
},
{
"esp_connection_id": 67890,
"percent": 100,
"segment_id": 1428
}
]
} |
Example - Split campaign request sample
...
Response
The response will include newly created mailing campaign array of fields.
Error Codes
- 400 - Invalid data in request
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>
Description
This method updates an existing mailing campaign. If schedule_date is provided (as Unix timestamp), campaign will be scheduled.
Request
name
Required string
The campaign internal friendly name. For your use only.
description
Required string
The campaign description. For your use only
type
Optional string
Campaign type (campaign/split)
split_type
Optional string
Split campaign type (email/esp/subject)
favorite
Optional 1 or 0
Favorite on/off
schedule_date
Optional number
Delivery date & time as Unix timestamp
email_message
Required array of numbers
Email message id for this campaign
subject
Optional array of strings
Subjects to test in this split campaign. Required for "subject" split_type only
pre_process
Optional boolean
Start all campaign pre-sending processing prior to launch time, so campaign can start sending at the specific scheduled time
Default: TRUE
segments
Required array of numbers
Segments to associate with this campaign
whitelist_segment_ids
Optional array of numbers
Whitelist Segments to associate with this campaign
notify_onlaunch
Optional boolean
Sends you email notification on campaign launch. - Default: FALSE
notify_onfailed
Optional boolean
Sends you email notification if campaign failed. - Default: FALSE
notify_oncomplete
Optional boolean
Sends you email notification on campaign sent. - Default: FALSE
distribution
Required array of arrays - ESP distribution configuration.
You can specify multiple ESPs with different percentage of delivery.
You can have distribution by ESP connections, by ESP connections / domains and by ESP connections / segments
*esp_connection_id: Numeric ID of your ESP connection
*percent: Numeric percent of this ESP connection distribution
*domain: String of domain name or "default"
*segment_id: Numeric ID of your segment
time_to_send_config
Optional object
Define Campaign Throttling - if provided you must have the following fields:
*delivery_timing_type : string - must be "throttling"
*throttling_type : string - "hours" / "emails_per_day"
*hours : integer - required when throttling_type is hours
*emails : integer - required when throttling_type is emails_per_day
Notice: "time_to_send_config" is replacing the old "span_type", "span_active" and "span_value" configurations that are deprecated and soon will stop being supported.
| Code Block |
|---|
// Throttling "emails_per_day" example
{
"time_to_send_config" : {
"delivery_timing_type" : "throttling",
"throttling_type": "emails_per_day",
"emails": 5000
}
}
|
| Code Block |
|---|
// Throttling "hours" example
{
"time_to_send_config" : {
"delivery_timing_type" : "throttling",
"throttling_type": "hours",
"hours": 50
}
}
|
emails_limit
Optional number
Limit the total number of messages to be sent for this campaign
tracking_domain
Optional string
Override default tracking domain
image_domain
Optional string
Override default image domain
Example - Regular campaign update request sample
PUT URL: https://api.ongage.net/<list_id>/api/mailings/<campaign_id>
| Code Block |
|---|
{
"typename": "splitMy new campaign",
"split_typedescription": "emailHandle with care",
"nameemail_message": "Split[ 227 email],
messages 50/50 to 1 Segment using 1 Sender Connection",
"email_message": [ "953", "954" ],
"segments": [ "31448"1429 ],
"distribution": [
{
"esp_connection_id":" 12345" ,
"percent":" 100"
}
],
"schedule_date": "2018-11-30 08:24",
"notify_onlaunch": "0",
"notify_onfailed": "0",
"notify_oncomplete": "0"
} |
Example - Split campaign request sample with winner sent after 24 hours
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{ "name":"A/B Split Test client scenario", "split_type":"email", "email_message":[ "12344", "54467" ], "whitelist_segment_ids":null, "segments":[ "123454", "764634" ], "esp_optional_routes":"segment", "segment_esp_distribution_by":"quota", "distribution":[ { "segment_id":"123454", "esp_connection_id":"76644" }, { "segment_id":"764634", } |
Response
The response will include mailing campaign's array of fields. Might also include a warning f request scheduled time is less than 30 minutes from now.
Error Codes
- 400 - Invalid data in request
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/abort
Description
This method is used to toggle campaign status On Hold / Stopped / In Progress.
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/cancel
Description
This method is used to cancel/delete an existing mailing campaign.
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/unschedule
Description
This method is used to Un-schedule a campaign. This will set the campaign status to "New".
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/revive
Description
This method Revives a canceled/deleted campaign.
Additional Examples
Example - Regular campaign request sample with ESP connection/domain distribution
POST URL: https://api.ongage.net/<list_id>/api/mailings
IMPORTANT - In case of domain distribution you must specify the default distribution for the rest of the domains as well.
| Code Block |
|---|
{ "name": "New campaign with domain distribution", "description": "Handle with care", "email_message": [ 27 ], "segments": [ 1429 ], "distribution": [ { "esp_connection_id":"98875" 12345, } ], "time_to_send_config":{percent": 100, "delivery_timing_typedomain":"schedule_date" "gmail.com" }, "schedule_date":"01/12/2021 17:15", { "delivery_timing_type":"per_timezone", "schedule_hour":"17", "scheduleesp_connection_minuteid":"15" 67890, "type":"split", "has_winner_settings":true, "winner_is_quota_percent":"1" 100, "winner_quota_value":"20", "winner_conversion_field":"unique_opens", "winner_send_after_hoursdomain": "24default" // Up to and not more than 24} Hours ] } |
Example -
...
Regular campaign request sample
...
with ESP connection / segments distribution
POST URL: https://api.ongage.net/<list_id>/api/mailings
IMPORTANT - The only allowed segment ids in this distribution are the ones provided in the segments array.
| Code Block |
|---|
{
"name": "A/B winner Split by 50/50 without Segmentation routingNew campaign with segments distribution",
"message_typedescription":"email_message "Handle with care",
"splitemail_typemessage":"esp" [ 27 ],
"espssegments": [ 1429, 1428 ],
"1233",distribution": [
{
"6577" ], "emailesp_connection_messageid":[ 12345,
"12345" ], "segmentspercent":[ 100,
"1234" ], "espsegment_optional_routesid":"single", 1429
"distribution":[ },
{
"esp_connection_id":"1233", 67890,
"isp_idpercent":0 100,
"percent "segment_id":50 1428
},
]
} |
Example - Split campaign request sample
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{
"esp_connection_id"type": "6577split",
"ispsplit_idtype":0 "email",
"percent"name":50 "Split 2 email messages 50/50 to }1 Segment ],
"time_to_send_config":{
using 1 Sender Connection",
"deliveryemail_timing_typemessage":"schedule_date"
} [ "953", "954" ],
"delivery_timing_typesegments":"per_timezone" [ "31448" ],
"has_winner_settings":true,distribution": [
{
"winner_is_quota_percent":"1", "winner_quota_value":"2", "winneresp_conversionconnection_fieldid":"unique_opens12345",
"winner_send_after_hours "percent":"1",100"
}
"schedule_hour":"10"],
"schedule_minutedate":"39 "2018-11-30 08:24",
"typenotify_onlaunch": "split0",
"usenotify_default_esponfailed":true "0",
"schedulenotify_dateoncomplete":"01/12/2021 10:39 "0"
} |
Example -
...
Split campaign request sample with winner sent after 24 hours
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{
"name": "My new SMS campaign"A/B Split Test client scenario",
"descriptionsplit_type": "Handle with careemail",
"email_message":[ [ 27"12344", "54467" ],
"segmentswhitelist_segment_ids": [ 1429 ]null,
"segments_excluded": [ 1520 ],
"distribution123454":, ["764634" ],
{"esp_connectionoptional_idroutes": 19999, "percent": 100 }
]segment",
"favoritesegment_esp_distribution_by": false"quota",
"schedule_datedistribution":[
1393738129
} |
Example - Test campaign request sample
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{ "is_test": true, "segment_id":"123454", "nameesp_connection_id": "My test campaign""76644" }, "description": "My description", { "email_message": [ 27 ], "recipientssegment_id": [ "john@doe.com"764634", "another@email.com" ], "esp_connection_id": 19999, "favorite": false,"98875" "prepend_test_to_subject": true } |
Response
The response will include newly created mailing campaign array of fields.
Error Codes
- 400 - Invalid data in request
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>
Description
This method updates an existing mailing campaign. If schedule_date is provided (as Unix timestamp), campaign will be scheduled.
Request
name
Required string
The campaign internal friendly name. For your use only.
description
Required string
The campaign description. For your use only
type
Optional string
Campaign type (campaign/split)
split_type
Optional string
Split campaign type (email/esp/subject)
favorite
Optional 1 or 0
Favorite on/off
schedule_date
Optional number
Delivery date & time as Unix timestamp
email_message
Required array of numbers
Email message id for this campaign
subject
Optional array of strings
Subjects to test in this split campaign. Required for "subject" split_type only
pre_process
Optional boolean
Start all campaign pre-sending processing prior to launch time, so campaign can start sending at the specific scheduled time
Default: TRUE
segments
Required array of numbers
Segments to associate with this campaign
whitelist_segment_ids
Optional array of numbers
Whitelist Segments to associate with this campaign
notify_onlaunch
Optional boolean
Sends you email notification on campaign launch. - Default: FALSE
notify_onfailed
Optional boolean
Sends you email notification if campaign failed. - Default: FALSE
notify_oncomplete
Optional boolean
Sends you email notification on campaign sent. - Default: FALSE
distribution
Required array of arrays - ESP distribution configuration.
You can specify multiple ESPs with different percentage of delivery.
You can have distribution by ESP connections, by ESP connections / domains and by ESP connections / segments
*esp_connection_id: Numeric ID of your ESP connection
*percent: Numeric percent of this ESP connection distribution
*domain: String of domain name or "default"
*segment_id: Numeric ID of your segment
time_to_send_config
Optional object
Define Campaign Throttling - if provided you must have the following fields:
*delivery_timing_type : string - must be "throttling"
*throttling_type : string - "hours" / "emails_per_day"
*hours : integer - required when throttling_type is hours
*emails : integer - required when throttling_type is emails_per_day
Notice: "time_to_send_config" is replacing the old "span_type", "span_active" and "span_value" configurations that are deprecated and soon will stop being supported.
| Code Block |
|---|
// Throttling "emails_per_day" example { } ], "time_to_send_config":{ "delivery_timing_type":"schedule_date" }, "schedule_date":"01/12/2021 17:15", "delivery_timing_type":"per_timezone", "schedule_hour":"17", "schedule_minute":"15", "type":"split", "has_winner_settings":true, "winner_is_quota_percent":"1", "winner_quota_value":"20", "winner_conversion_field":"unique_opens", "winner_send_after_hours":"24" // Up to and not more than 24 Hours } |
Example - Split campaign request sample 50/50 Split without segmentation routing
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{ "name":"A/B winner Split by 50/50 without Segmentation routing", "message_type":"email_message", "split_type":"esp", "esps":[ "1233", "6577" ], "email_message":[ "12345" ], "segments":[ "1234" ], "esp_optional_routes":"single", "distribution":[ { "esp_connection_id":"1233", "isp_id":0, "percent":50 }, { "esp_connection_id":"6577", "isp_id":0, "percent":50 } ], "time_to_send_config" :{ { "delivery_timing_type" : "throttling",schedule_date" }, "throttlingdelivery_timing_type": "emails_per_daytimezone", "has_winner_settings":true, "emailswinner_is_quota_percent":"1", 5000 "winner_quota_value":"2", } } |
| Code Block |
// Throttling "hours" example {"winner_conversion_field":"unique_opens", "winner_send_after_hours":"1", "time_to_send_config" : {schedule_hour":"10", "deliveryschedule_timing_typeminute" : "throttling39", "throttling_type":"split", "hours", "use_default_esp":true, "hoursschedule_date": 50 } } |
emails_limit
Optional number
Limit the total number of messages to be sent for this campaign
tracking_domain
Optional string
Override default tracking domain
image_domain
Optional string
Override default image domain
Example - Regular campaign update request sample
...
"01/12/2021 10:39"
} |
Example - SMS campaign request sample
POST URL: https://api.ongage.net/<list_id>/api/mailings/<campaign_id>
| Code Block |
|---|
{
"name": "My new SMS campaign",
"description": "Handle with care",
"email_message": [ 27 ],
"segments": [ 1429 ],
"distributionsegments_excluded": [ 1520 ],
{"distribution": [
{"esp_connection_id": 12345 19999, "percent": 100 }
],
"percentfavorite": 100false,
}
]
} |
Response
The response will include mailing campaign's array of fields. Might also include a warning f request scheduled time is less than 30 minutes from now.
Error Codes
- 400 - Invalid data in request
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/abort
Description
This method is used to toggle campaign status On Hold / Stopped / In Progress.
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/cancel
Description
This method is used to cancel/delete an existing mailing campaign.
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/unschedule
Description
This method is used to Un-schedule a campaign. This will set the campaign status to "New".
Error Codes
403 - Permission error
404 - Campaign not found
PUT /api/mailings/<Campaign ID>/revive
Description
...
"schedule_date": 1393738129
} |
Example - Test campaign request sample
POST URL: https://api.ongage.net/<list_id>/api/mailings
| Code Block |
|---|
{
"is_test": true,
"name": "My test campaign",
"description": "My description",
"email_message": [ 27 ],
"recipients": [ "john@doe.com", "another@email.com" ],
"esp_connection_id": 19999,
"favorite": false,
"prepend_test_to_subject": true
} |