Campaign Mailing API Methods

Table of Contents:

Intro

(info) 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>

Response Sample - With error status

Error Codes

  • 403 - Permission error

  • 404 - Campaign not found


Campaign Status Codes

StatusCode
NEW60001
SCHEDULED60002
IN_PROGRESS60003
COMPLETED60004
ERROR60005
CANCELLED60006
DELETED60007
COMPLETED_WITH_ERRORS60008
ON_HOLD60009
STOPPED60010

GET /api/mailings

Description 

This method gives collection of campaigns in response.

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

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. 

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.

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

Example - Regular campaign request sample

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

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.

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>

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.

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.

Request Example - Split campaign request sample

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

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

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

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

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

Request Example - SMS campaign request sample

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

Request Example - Test campaign request sample

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