Table of Contents:
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.
This method fetches a single mailing, including email messages, segments and distribution.
GET URL: https://api.ongage.net/<list_id>/api/mailings/<campaign_id>
{ "metadata": { "error": false }, "payload": { "id": "111670", "type": "campaign", "account_id": "26099", "list_id": "23939", "is_test": "0", "split_type": null, "schedule_date": "0", "name": "My campaign name", "description": "My campaign description", "status": "60001", "status_desc": "New", "status_date": "1416399211", "created": "1416301061", "modified": "1416399607", "scheduled_by": "10", "deleted": "0", "segments": [ { "segment_id": "35412", "type": "Active", "name": "All list members", "last_count": "140", "exclude": "1" } ], "distribution": [ { "esp_id": "10", "esp_connection_id": "11058", "isp_id": null, "domain": "default", "percent": "100", "name": "Dyn" } ], "email_message": [ { "type": "email_message", "email_message_id": "2025", "name": "Email message name", "description": "", "subject": "Email message subject" } ] } } |
{ metadata:{ error:false }, payload:{ id:"28101660", type:"campaign", account_id:"1111", list_id:"1111", is_test:"1", split_type:null, schedule_date:"1453788025", name:"A friendly reminder from MyCompany regarding your subscription", description:null, status:"60005", status_desc:"Error", status_date:"1453788050", scheduled_by:"6975", notify_onlaunch:"0", notify_onfailed:"0", notify_oncomplete:"0", progress:"100", created:"1453788026", modified:"1453788050", deleted:"0", comment:"<ul><li>Message generation rejected. Please contact MyCompany.</li></ul>", segments:[ ], distribution:[ { esp_id:"01", esp_connection_id:"1234", isp_id:null, domain:"default", percent:"100", name:"ESP-Vendor" } ], esp_connections_quota:[ ], email_message:[ { type:"email_message", email_message_id:"652498", name:"[TE] - A friendly reminder from MyCompany regarding your subscription", description:"A friendly reminder from MyCompany regarding your subscription", subject:"A friendly reminder from MyCompany regarding your subscription", preview:"e652498.png", prefix:"0", fullname:"uploader " } ], } } |
403 - Permission error
404 - Campaign not found
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 |
This method gives collection of campaigns in response.
date_from
Optional int
Unix timestamp filter by schedule date
date_to
Optional int
Unix timestamp filter by schedule date
email_name
Optional string
Email name filter
mailing_name
Optional string
Mailing name filter
is_test
Optional boolean
Filter out test campaigns
offset
Optional int
limit
Optional int
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.
name
Required string
The campaign internal friendly name. For your use only.
list_id
Optional int
id of list to which this mailing should be attached to.
type
Optional string
Campaign type (campaign/split)
description
Required string
The campaign description. For your use only
split_type
Optional string
Split campaign type (email/esp/subject)
has_winner_settings
Optional boolean : True or False
True if A/B winner split campaign needs to be scheduled.
"winner_is_quota_percent" - Optional int - 1 to 100
"winner_quota_value" - Optional int - 1 to 100
"winner_conversion_field" - Required when "has_winner_settings" is True - string - unique_opens / unique_clicks
"winner_send_after_hours" - Required when "has_winner_settings" is True - int - Up to and not more than 24 hours
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 which are deprecated and soon will stop to be supported.
// Throttling "emails_per_day" example { "time_to_send_config" : { "delivery_timing_type" : "throttling", "throttling_type": "emails_per_day", "emails": 5000 } } |
// Throttling "hours" example { "time_to_send_config" : { "delivery_timing_type" : "throttling", "throttling_type": "hours", "hours": 50 } } |
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
segments
Required array of numbers
Segments to associate with this campaign
segments_excluded
Optional array of numbers
Segments IDs, to exclude from this campaign
whitelist_segment_ids
Optional array of numbers
Whitelist Segments to associate with 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
recipients
Optional array of strings
Array of email addresses. For Test Campaigns only ("is_test" is TRUE)
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
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
is_test
Optional boolean
Mark this campaign as a test campaign. - Default: FALSE
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "name": "My new campaign", "description": "Handle with care", "email_message": [ 27 ], "segments": [ 1429 ], "distribution": [ { "esp_connection_id": 12345 , "percent": 100 } ] } |
The response will include newly created mailing campaign array of fields.
403 - Permission error
404 - Campaign not found
This method updates an existing mailing campaign. If schedule_date is provided (as Unix timestamp), campaign will be scheduled.
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.
// Throttling "emails_per_day" example { "time_to_send_config" : { "delivery_timing_type" : "throttling", "throttling_type": "emails_per_day", "emails": 5000 } } |
// 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
PUT URL: https://api.ongage.net/<list_id>/api/mailings/<campaign_id>
{ "name": "My new campaign", "description": "Handle with care", "email_message": [ 27 ], "segments": [ 1429 ], "distribution": [ { "esp_connection_id": 12345 , "percent": 100 } ] } |
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.
403 - Permission error
404 - Campaign not found
This method is used to toggle campaign status On Hold / Stopped / In Progress.
403 - Permission error
404 - Campaign not found
This method is used to cancel/delete an existing mailing campaign.
403 - Permission error
404 - Campaign not found
This method is used to Un-schedule a campaign. This will set the campaign status to "New".
403 - Permission error
404 - Campaign not found
This method Revives a canceled/deleted campaign.
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.
{ "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" } ] } |
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.
{ "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 } ] } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "type": "split", "split_type": "email", "name": "Split 2 email messages 50/50 to 1 Segment using 1 Sender Connection", "email_message": [ "953", "954" ], "segments": [ "31448" ], "distribution": [ { "esp_connection_id":"12345", "percent":"100" } ], "schedule_date": "2018-11-30 08:24", "notify_onlaunch": "0", "notify_onfailed": "0", "notify_oncomplete": "0" } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "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", "esp_connection_id":"98875" } ], "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 } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "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":"schedule_date" }, "delivery_timing_type":"per_timezone", "has_winner_settings":true, "winner_is_quota_percent":"1", "winner_quota_value":"2", "winner_conversion_field":"unique_opens", "winner_send_after_hours":"1", "schedule_hour":"10", "schedule_minute":"39", "type":"split", "use_default_esp":true, "schedule_date":"01/12/2021 10:39" } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "name": "My new SMS campaign", "description": "Handle with care", "email_message": [ 27 ], "segments": [ 1429 ], "segments_excluded": [ 1520 ], "distribution": [ {"esp_connection_id": 19999, "percent": 100 } ], "favorite": false, "schedule_date": 1393738129 } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "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 } |
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "name": "Timezone test", "email_message": 12343, "segments": [45454], "distribution": [ { "esp_connection_id": 4453, "percent": 100 } ], "time_to_send_config":{ "schedule_type":"launch_now", "send_by_timezone":{ "timezone_source":"ip", "contact_field_id":"128296", // Add List Filed Id here "start_timezone":"Asia/Kolkata" }, "delivery_timing_type":"schedule_date" }, "schedule_now":true } |
send_by_timezone
Optional object
Define Timezone setting if you provide following fields:
*ip: float - Send by IP Address
*timezone : Send by Timezone
*zipcode : Send by ZIP Code
*airport: Send by Airport code
*contact_field_id: integer - List Field ID of the field where contacts details are added
*start_timezone: string - Starting timezone of the Campaign sent.
POST URL: https://api.ongage.net/<list_id>/api/mailings
{ "email_message": "12345", "name": “example", "keep_segment_sort": true, "segments": ["1233456"], "distribution": { { "esp_connection_id": "122456", "isp_id": "0", "percent": "100" } }, "emails_limit_active": true, "emails_limit_global_active": true, "emails_limit": "10" } |
keep_segment_sort
Optional boolean : True or False
*Enables option to send campaign by Selected Segment order until the quota is reached.
*Note: For this option to work, Campaign “emails_limit_global_active” must be true
emails_limit_global_active
Optional boolean: True or false
*it Defines Global Quota
emails_limit
Optional numeric
*Defines number of contacts limit you want to apply in the Campaign.