Transactional Mailing API Methods
Table of Contents:
Intro
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/transactional
Description
This method fetches a collection of transactional campaigns.
Request
list_id
Optional number - List ID
sort
Optional string - Column name
order
Optional string - "ASC" or "DESC"
offset
Optional int
limit
Optional int
POST /api/transactional
Description
This method creates a new transactional campaign.
Request
name
Required string
The transactional campaign internal friendly name. For your use only.
description
Required string
The transactional campaign description. For your use only
list_id
Optional int
id of list to which this transactional campaign should be attached to.
POST URL: https://api.ongage.net/<list_id>/api/transactional
// Request example
{ "name": "My Transactional", "description": "My first transactional campaign", "message_type": "email" }
Response
The response will include a newly created transactional campaign array of fields.
PUT /api/transactional/<Transactional Campaign ID>
Description
This method updates an existing transactional campaign.
Request
name
Required string
The transactional campaign internal friendly name. For your use only.
description
Required string
The transactional campaign description. For your use only
list_id
Optional int
id of list to which this transactional campaign should be attached to.
PUT URL: https://api.ongage.net/<list_id>/api/transactional/<transactional_campaign_id>
// Request example
{ "name": "My Transactional", "description": "My first transactional campaign" }
POST /api/transactional/send
Description
This method is used to send a transactional message.
Note: Not all ESPs/SMTP relays support transactional calls.
Request
message_id
Required number
The message (email or SMS) that will be used for delivery.
recipients
Required array of strings
Recipients for delivery. This must be array of emails.
Note: In the case of SMS Transactional campaigns; you can also use a mobile number (in the format suggested by SMS vendor you are using). We recommend using this for testing purposes only; because Open/clicks will not register when a mobile number is used as a recipient.
campaign_id
Optional number
Related transactional campaign for delivery. If not provided the default transactional campaign will be used.
sending_connection_id
Optional number
The connection (ESP/SMS) that will be used in the transactional sending. If not provided the connection that was defined in the default transactional campaign will be used
check_status
Optional boolean - Default "false"
When set to true, this takes into account the contact’s status (unsubscribe, bounced, etc.) and don't send transactional email if status is not active.
check_global_and_list_suppression
Optional boolean - Default "false"
When set true take into account if email resides in any applicable suppression list (only in global or list scope), and if so-- don't send
message_dynamic_fields
Optional Object
You can pass in key/values, e.g., "message_dynamic_fields": { "receipt_id": 12345, "uid": 6789 }, so that you can use the keys as dynamic variables in the body of the message. e.g., This is your receipt {{receipt_id}}.
message_dynamic_fields_per_recipient
Optional array with recipient and key_value_collection - e.g., "message_dynamic_fields_per_recipient":[
{ "recipient":"email@email.com", "key_value_collection":{ "receipt_id":
12345, "uid": 6789 } } ], so that you can use the keys as dynamic variables in the body of the message e.g., This is your receipt {{receipt_id}}.
campaign_suppression_list_ids
Optional array with campaign level suppression list IDs - e.g., "campaign_suppression_list_ids":[ 4060001, 4060002 ]
cc_whitelist_segment_id
Optional integer
This feature enables marketers to send an exact copy as Cc, to a list of staff members/stake holders, for legal or monitoring purposes. For each message sent via this Transactional campaign, a Cc (copy), will be sent to those email addresses associated with the selected Whitelist Segment. Not all SMTPs support the Cc feature, see our online help for a list of those that do.
bcc_whitelist_segment_id
Optional integer
This feature enables marketers to send an exact copy as Bcc, to a list of staff members/stake holders, for legal or monitoring purposes. For each message sent via this Transactional campaign, a Bcc (copy), will be sent to those email addresses associated with the selected Whitelist Segment. Not all SMTPs support the Bcc feature, see our online help for a list of those that do.
create_contact
Optional boolean - Default "false"
This feature enables marketers to add contacts in list when the respective contact used in request is not part of the sending list.
Example - Basic usage
POST URL: https://api.ongage.net/<list_id>/api/transactional/send
{
"message_id": 168,
"recipients": [ "email@email.com", "..." ]
}
Transactional Emails have a flag, that indicate if you want the transactional email to take into account the contact’s status (unsubscribed, bounced, etc.) or not. If yes, then set check_status: true. Similarly there's a flag check_suppression: true to check and take into account if the email resides in a suppression list or not. Here's an example of how to use these:
{
"message_id": 168,
"campaign_id": 213,
"recipients": [ "email@email.com", "..." ],
"check_status": true,
"check_suppression": true
}
POST /api/transactional/send_embed_content
Description
This method is used to send a transactional message with embedded content (without message ID).
Note: Not all ESPs/SMTP relays support transactional calls.
Request
message
Required object - Email content for delivery. Must contain the following keys:
*subject - Required string
*content_html - Required string - Only for transactional email
*content_text - Required string - Only for transactional SMS / plaintext emails
*addresses - Required object - must have the following fields:
*from_name - Required string
*from_address - Required string when transactional is of email type
*reply_address - Required string when transactional is of email type
recipients
Required array of strings
Recipients for delivery. This must be an array of emails.
Note: In the case of SMS Transactional campaigns; you can also use a mobile number (in the format suggested by SMS vendor you are using). We recommend using this for testing purposes only; because Open/clicks will not register when a mobile number is used as a recipient.
campaign_id
Optional number
Related transactional campaign for delivery. If not provided the default transactional campaign will be used.
sending_connection_id
Optional number
The connection (ESP/SMS) that will be used in the transactional sending. If not provided the connection that was defined in the default transactional campaign will be used
disable_unsubscribe
Optional boolean
The email message will not include unsubscribe link. Default - False
schedule_date
Optional number or string
String of delivery date or time as Unix timestamp
delay_send
Optional number or string
String of delay time (HH:MM) or number of seconds to delay (e.g. 3600 stands for 1 hour of delay).
check_status
Optional boolean - Default "false"
When set to true, this takes into account the contact’s status (unsubscribe, bounced, etc.) and don't send a transactional email if the status is not active.
check_global_and_list_suppression
Optional boolean - Default "false"
When set true take into account if email resides in any applicable suppression list (only in global or list scope), and if so-- don't send
message_dynamic_fields
Optional Object
You can pass in key/values, e.g., "message_dynamic_fields": { "receipt_id": 12345, "uid": 6789 }, so that you can use the keys as dynamic variables in the body of the message. e.g., This is your receipt {{receipt_id}}.
message_dynamic_fields_per_recipient
Optional array with recipient and key_value_collection - e.g., "message_dynamic_fields_per_recipient":[
{ "recipient":"email@email.com", "key_value_collection":{ "receipt_id":
12345, "uid": 6789 } } ], so that you can use the keys as dynamic variables in the body of the message e.g., This is your receipt {{receipt_id}}.
campaign_suppression_list_ids
Optional array with campaign level suppression list IDs - e.g., "campaign_suppression_list_ids":[ 4060001, 4060002 ]
cc_whitelist_segment_id
Optional integer
This feature enables marketers to send an exact copy as Cc, to a list of staff members/stake holders, for legal or monitoring purposes. For each message sent via this Transactional campaign, a Cc (copy), will be sent to those email addresses associated with the selected Whitelist Segment. Not all SMTPs support the Cc feature, see our online help for a list of those that do.
bcc_whitelist_segment_id
Optional integer
This feature enables marketers to send an exact copy as Bcc, to a list of staff members/stake holders, for legal or monitoring purposes. For each message sent via this Transactional campaign, a Bcc (copy), will be sent to those email addresses associated with the selected Whitelist Segment. Not all SMTPs support the Bcc feature, see our online help for a list of those that do.
create_contact
Optional boolean - Default "false"
This feature enables marketers to add contacts in list when the respective contact used in request is not part of the sending list.
Example - Regular embedded transactional email sending
POST URL: https://api.ongage.net/<list_id>/api/transactional/send_embed_content
{
"message": {
"subject": "Hello!",
"content_html" :"<html><body><p>This is my content</p></body></html>",
"addresses": {
"from_name": "John Doe",
"from_address": "john@doe.com",
"reply_address": "john@doe.com"
}
},
"campaign_id": 213,
"recipients": [ "email@email.com", "..." ],
"sending_connection_id": 1234
}
POST /api/notify_transactions
This method is deprecated, but we're continuing to support it for the long run.
At your convenience please upgrade to: POST /api/transactional/send or POST /api/transactional/send_embed_content method mentioned above.
Description
This method is used to send a new request for an ongoing transactional mailing.
Note: Not all ESPs/SMTP relays support transactional calls.
Request
recipients
Required array of strings
Recipients for delivery. This must be array of emails.
Note: In the case of SMS Transactional campaigns; you can also use a mobile number (in the format suggested by SMS vendor you are using). We recommend using this for testing purposes only; because Open/clicks will not register when a mobile number is used as a recipient.
mailing_id
Optional number
Related transactional campaign for delivery. If not provided the default transactional campaign will be used.
email_message_id
Required number
Existing email for delivery. You must provide email_message_id or email_message
disable_unsubscribe
Optional boolean
The email message will not include unsubscribe link. Default - False
schedule_date
Optional number or string
String of delivery date or time as Unix timestamp
delay_send
Optional number or string
String of delay time (HH:MM) or number of seconds to delay (e.g. 3600 stands for 1 hour of delay).
check_status
Optional boolean - Default "false"
When set to true, this takes into account the contact’s status (unsubscribe, bounced, etc.) and don't send transactional email if status is not active.
check_global_and_list_suppression
Optional boolean - Default "false"
When set true take into account if email resides in any applicable suppression list (only in global or list scope), and if so-- don't send
email_message
Optional array of key/value - Email content for delivery. Providing a email_message_id will override this parameter
*subject string
*name string
*content_html string
*content_text string
*addresses array
addresses
Required if sent 'email_message' array of arrays:
*from_name: From name
*from_address: From address
*reply_address: Reply address
*esp_connection_id
distribution
Optional one of the next options:
Empty: Will use current default ESP distribution configuration, in case there is no default configured, an error will be raised
ID: Numeric id of the ECID (ESP Connection ID) you want to use. That would be the number that appears in the ECID column next to that ESP connection, in your My Connections screen.
Array: Will use given ESP array:
*esp_connection_id: Numeric ID (Note that esp_id is deprecated)
*domain: String of domain name or "default"
*percent: Percentage of contacts to send through this ESP
message_dynamic_fields
Optional Object
You can pass in key/values, e.g., "message_dynamic_fields": { "receipt_id": 12345, "uid": 6789 }, so that you can use the keys as dynamic variables in the body of the message. e.g., This is your receipt {{receipt_id}}.
message_dynamic_fields_per_recipient
Optional array with recipient and key_value_collection - e.g., "message_dynamic_fields_per_recipient":[
{ "recipient":"email@email.com", "key_value_collection":{ "receipt_id":
12345, "uid": 6789 } } ], so that you can use the keys as dynamic variables in the body of the message e.g., This is your receipt {{receipt_id}}.
campaign_suppression_list_ids
Optional array with campaign level suppression list IDs - e.g., "campaign_suppression_list_ids":[ 4060001, 4060002 ]
Example - Using email/sms message ID
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ],
"email_message_id": 168, // `email_message_id` will override 'email_message' collection if exist
"distribution": [
{
"esp_connection_id": 2,
"domain": "default"
}
]
}
Transactional Emails have a flag, that indicates if you want the transactional email to take into account the contact’s status (unsubscribed, bounced, etc.) or not. If yes, then set check_status: true. Similarly, there's a flag check_suppression: true to check and take into account if the email resides in a suppression list or not. Here's an example of how to use these:
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ],
"email_message_id": 168, // `email_message_id` will override 'email_message' collection
"check_status": "1",
"check_suppression": "1",
"email_message": {
// All fields of email message...
}
Response
Same as provided request
Error codes
- 403 - Permission error
- 404 - Email/Campaign not found
DELETE /API/transactional/<Transactional Campaign ID>
Description
This method deletes a transactional campaign.
Additional Examples
Request Example - Transactional Send - Using specific transactional campaign and specific connection
POST URL: https://api.ongage.net/<list_id>/api/transactional_send
{
"message_id":4567,
"recipients": [ "email@email.com", "..." ],
"campaign_id": 213,
"sending_connection_id": 1234
}
Request Example - Transactional Send - using dynamic fields per recipient
POST URL: https://api.ongage.net/<list_id>/api/transactional/send
// Email with the following HTML
<p>
Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!
</p>
{
"message_id":4567, // This is the id of the email from above,
"campaign_id": 213,
"recipients": [ "john@email.com", "jane@email.com" ],
"sending_connection_id": 1234,
"message_dynamic_fields_per_recipient":[
{
"recipient":"john@email.com",
"key_value_collection": {
"first_name":"John",
"age": 34
}
},
{
"recipient":"jane@email.com",
"key_value_collection": {
"first_name": "Jane",
"age": 28
}
}
]
}
Request Example - Transactional Send - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/transactional/send
{
"message_id":45678,
"campaign_id": 213,
"recipients": [ "email@email.com", "..." ],
"sending_connection_id": 556677,
"disable_unsubscribe": true
}
Request Example - Embedded content - Regular embedded transactional SMS sending
POST URL: https://api.ongage.net/<list_id>/api/transactional/send_embed_content
{
"message": {
"subject": "Hello!",
"content_text" :"This is my content",
"addresses": {
"from_name": "John Doe"
}
},
"campaign_id": 213,
"recipients": [ "email@email.com", "..." ],
"sending_connection_id": 1234
}
Request Example - Embedded content - Embedded transactional email with "message_dynamic_fields"
POST URL: https://api/ongage.net/<list_id>/api/transactional/send_embed_content
{
"message": {
"subject": "Hello!",
"content_html" :"<p>You have special discount of {{special_discount}}% until {{expiration_date}}</p>",
"addresses": {
"from_name": "John Doe",
"from_address": "john@doe.com",
"reply_address": "john@doe.com"
},
"campaign_id": 213,
"recipients": [ "email@email.com", "..." ],
"sending_connection_id": 1234,
"message_dynamic_fields": { "special_discount": "50", "expiration_date": "01/01/2020" }
}
}
Request Example - Notify Transactions - Using email message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ],
"email_message": {
"subject": "Email Subject",
"content_html": "<html>Content HTML</html>",
"content_text": "Content Text",
"addresses": [
{
"from_name": "My name",
"from_address": "my@address.com",
"reply_address": "my@address.com",
"esp_connection_id": 1
}
]
},
"distribution": [
{
"esp_connection_id": 2,
"domain": "default",
"percent": 100
}
],
"message_dynamic_fields": { "test": 234, "uid": 32431 },
"disable_unsubscribe": true
}
Request Example - Notify Transactions - Using dynamic fields per recipient
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
{
"mailing_id": 213,
"recipients": [ "john@email.com", "jane@email.com" ],
"email_message": {
"subject": "Email Subject",
"content_html": "<html><p>Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!</p></html>",
"content_text": "Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!",
"addresses": [{
"from_name": "My name",
"from_address": "my@address.com",
"reply_address": "my@address.com",
"esp_connection_id": 1
}]
},
"distribution": [
{
"esp_connection_id": 2,
"domain": "default",
"percent": 100
}
],
"message_dynamic_fields_per_recipient":[
{
"recipient":"john@email.com",
"key_value_collection": {
"first_name":"John",
"age": 34
}
},
{
"recipient":"jane@email.com",
"key_value_collection": {
"first_name": "Jane",
"age": 28
}
}
]
}
Request Example - Notify Transactions - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ], // You can use Mobile number with Country code (+1XXXXXXXXXX) as well in place of email address.
"email_message": {
"content_text": "SMS content",
"addresses": [
{
"from_name": "My name",
"esp_connection_id": 1
}
]
},
"distribution": [
{
"esp_connection_id": 1,
"domain": "default",
"percent": 100
}
],
"message_dynamic_fields": { "test": 234, "uid": 32431 },
"disable_unsubscribe": true
}
Appendix
SMTPs that support Cc and Bcc
SparkPost