Campaign Mailing API Methods

Table of Contents:

Intro

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.

Response Sample

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"
   }
  ]
 }
}

Response Sample - With error status

{
  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 "
         }
      ],
   }
}

Error Codes

403 - Permission error
404 - Campaign not found

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 will retrieve all the campaigns in a given list based on the optional filters detailed below.

Request

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

Response Sample

Get URL: https://api.ongage.net/<list_id>/api/mailings/>

{
  "metadata": {
    "error": false,
    "total": "1"
  },
  "payload": [
    {
      "id": "1234567890",
      "name": "[TEST] Ongage Support test",
      "schedule_date": "1638229112",
      "type": "campaign",
      "split_type": null,
      "status": "60004",
      "list_id": "1234567",
      "status_desc": "Completed",
      "status_date": "1638229129",
      "scheduled_by": "23913",
      "has_quota": "0",
      "split_subject_content_email_id": null,
      "created_by": "23913",
      "favorite": "0",
      "created": "1638229112",
      "modified": "1638229724",
      "deleted": "0",
      "is_test": "1",
      "progress": "100",
      "manager": "Mr. Manager",
      "targeted": "1",
      "cannot_resume": "0",
      "cannot_resume_reason": "",
      "original_email_message_id": "12345678",
      "ox_data": null,
      "sending_start_date": "1638229119",
      "sending_end_date": "1638229128",
      "estimated_sending_end_date": "0",
      "emails_limit": "0",
      "report": 1,
      "test": 0,
      "cancel": 0,
      "schedule": "delivered",
      "esps": "SparkPost",
      "comment": "",
      "email_id": "12345678",
      "email_name": "Ongage Support test 34091",
      "message_type": "email_message",
      "is_email_designer": "0"
    }
  ]
}

POST /api/mailings

Description

This method creates a new 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.

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.

sto

Optional object

Enable send time optimization, Let Ongage pick the best time to send

// 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

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

Defines Global Quota

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.

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

Example - Regular campaign request sample

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
     }
   ],
  "schedule_date": "11/11/1111 11:11"
}

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

POST /api/mailings/<Campaign ID>duplicate

Description

This method is used for duplicating Bulk campaigns. Please note that duplicating A/B Split or Test Campaign is not supported.

Request

email_message_id

Required number

The email message that you want to use in the copied campaign.

segments

Optional array of numbers

Include segments that you want to use in the copied campaign.

segments_excluded

Optional array of numbers

Exclude segment/s that you want to use in the copied campaign.

add_copy_to_title

Optional Boolean

Use this if you want to append (Copy) in copied campaign name.

Example - Regular Bulk campaign request sample

POST URL: https://api.ongage.net/mailings/<Campaign ID>/duplicate

{
  "email_message_id":123456, ///mendatory//
   "segments":[ ],  ///optional///
   "segments_excluded":[ ], ///optional///
   "add_copy_to_title": true/false, ///optional///
}

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.

// 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

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

Defines Global Quota

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.

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>

{
   "name": "My new campaign",
   "description": "Handle with care",
   "email_message": [ 27 ],
   "segments": [ 1429 ],
   "distribution": [
     {
            "esp_connection_id": 12345 ,
            "percent": 100
     }
   ]
}

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

Request 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.

{
   "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"
     }
   ]
}

Request 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.

{
   "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
     }
   ]
}

Request Example - Split campaign request sample

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"
}

Request Example - Split campaign request sample with winner sent after 24 hours

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   
}

Request Example - Split campaign request sample 50/50 Split without segmentation routing

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"
}

Request Example - SMS campaign request sample

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
}

Request Example - Test campaign request sample

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
}

Alternatively you can indicate a Whitelist Segment

{
   "is_test": true,
   "name": "My test campaign",
   "description": "My description",
   "whitelist_segment_ids": [ 12345678 ], 
   "email_message": [ 12345678 ],
   "esp_connection_id": 12345,
   "favorite": false,
   "prepend_test_to_subject": true
}

Request Example - Schedule Campaign to Send By Timezone (And Launch Campaign Immediately)

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
}

Request Example - Send Campaign with Segment order until quota

POST URL: https://api.ongage.net/<list_id>/api/mailings

{
	"name": “example",
	"email_message": "12345",
	"keep_segment_sort": true,
	"segments": ["1233456"],
	"distribution": {
		 {
			"esp_connection_id": "122456",
			"percent": "100"
		}
	},
    "schedule_date": "11/11/1111 11:11",	
    "emails_limit_active": true,
	"emails_limit_global_active": true,
	"emails_limit": "10"
}

Request Example - Send Campaign with Send Time Optimization (STO)

POST URL: https://api.ongage.net/<list_id>/api/mailings

{
  "name": "STO test",
  "email_message": 12343,
  "segments": [
    45454
  ],
  "distribution": [
    {
      "esp_connection_id": 4453,
      "percent": 100
    }
  ],
  "time_to_send_config": {
    "sto": {
      "enabled": true,
      "type": "regular"
    },
    "delivery_timing_type": "schedule_date"
  },
  "schedule_date": "11/11/1111 11:11"
}