Table of Contents:
Table of Contents minLevel 2
Intro
| Info |
|---|
| The Transactional API gives you access to all your transactional 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/transactional
DescriptionÂ
This method fetches a collection of transactional campaigns.
...
Optional int
limit
Optional int
POST /api/transactional
DescriptionÂ
This method creates a new transactional campaign.
...
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.
...
| Code Block |
|---|
// Request example
{ "name": "My Transactional", "description": "My first transactional campaign" }
|
POST /api/transactional/send
DescriptionÂ
This method is used to send transactional message.
...
| Code Block |
|---|
{
"message_id": 168,
"recipients": [ "email@email.com", "..." ]
} |
Example - Using specific transactional campaign and specific connection
POST URL: https://api.ongage.net/<list_id>/api/transactional_send
...
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:
| Code Block |
|---|
{ "message_id":4567 168, "recipients "campaign_id": 213, [ "email@email "recipients": [ "email@email.com", "..." ], "campaigncheck_idstatus": 213true, "sendingcheck_connection_idsuppression": 1234true } |
...
POST
...
/api/
...
| Code Block |
|---|
// Email with the following HTML
<p>
Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!
</p> |
| Code Block |
|---|
{
"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
}
}
]
} |
...
transactional/send_embed_content
DescriptionÂ
This method is used to send transactional message with embedded content (without message ID).
 Note: Not all ESPs/SMTP relays support transactional calls.
Request
message_id
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 that for transactional SMS, array of emails is also required.
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_sendembed_content
| Code Block |
|---|
{
"message_id":45678, {
"campaign_idsubject": 213,"Hello!",
"recipientscontent_html" :"<html><body><p>This [ "email@email.com", "..." ],is my content</p></body></html>",
"addresses": {
"sendingfrom_connection_idname": 556677"John Doe",
"disable_unsubscribe": true
} |
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:
| Code Block |
|---|
{ "from_address": "john@doe.com", "messagereply_idaddress": 168, "john@doe.com" } }, "campaign_id": 213, "recipients": [ "email@email.com", "..." ], "check_status": true, "check_suppressionsending_connection_id": true1234 } |
Example - Regular embedded transactional SMS sending
POST URL: https://api.ongage.net/<list_id>/api/transactional/send_embed_
...
DescriptionÂ
This method is used to send transactional message with embedded content (without message ID).
 Note: Not all ESPs/SMTP relays support transactional calls.
Request
message_id
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 that for transactional SMS, array of emails is also required.
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
...
content
| Code Block |
|---|
{
"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
} |
Example - Embedded transactional email with "message_dynamic_fields"
POST URL: https://api/ongage.net/<list_id>/api/transactional/send_embed_content
| Code Block |
|---|
{ "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": |
...
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.
...
"01/01/2020" }
}
} |
POST /api/notify_transactions
| Warning |
|---|
|
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 that for transactional SMS, array of emails is also required.
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"
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
| Code Block |
|---|
{
"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
} |
Example - Regular embedded transactional SMS sending
POST URL: https://api.ongage.net/<list_id>/api/transactional/send_embed_content
| Code Block |
|---|
{
"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
} |
Example - Embedded transactional email with "message_dynamic_fields"
POST URL: https://api/ongage.net/<list_id>/api/transactional/send_embed_content
...
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
| Code Block |
|---|
{ "mailing_id": 213, "recipients": [ "email@email.com", "..." ], "sendingemail_connectionmessage_id": 1234168, // `email_message_id` will override "message_dynamic_fields": { "special_discount": "50", "expiration_date": "01/01/2020" } } } |
POST /api/notify_transactions
| Warning |
|---|
|
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 that for transactional SMS, array of emails is also required.
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
| Code Block |
|---|
{ "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"'email_message' collection if exist "distribution": [ { "esp_connection_id": 2, "domain": "default" } ] } |
Example - Using email message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{
"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
} |
Example - Using dynamic fields per recipient
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{
"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
}
}
]
} |
Example - Using
...
SMS message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ],
"email_message": {
"subject": "Email Subject",
"content_htmltext": "<html>Content HTML</html>",
"content_text": "Content Text",
"addresses": [
{
"from_name": "My name",
SMS content",
"from_addressaddresses": "my@address.com",[
{
"replyfrom_addressname": "my@address.comMy name",
"esp_connection_id": 1
}
]
},
"distribution": [
{
"esp_connection_id": 21,
"domain": "default",
"percent": 100
}
],
"message_dynamic_fields": { "test": 234, "uid": 32431 },
"disable_unsubscribe": true
} |
Example - Using dynamic fields per recipient
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{ , "uid": 32431 }, "disable_unsubscribe": true } |
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:
| Code Block |
|---|
{ "mailing_id": 213, "recipients": [ "john@emailemail@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>", "email_message_id": 168, // `email_message_id` will override 'email_message' collection "contentcheck_textstatus": "Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!1", "check_suppression": "1", "addressesemail_message": [{ "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 } }, // 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
| Code Block |
|---|
{
"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
| Code Block |
|---|
// Email with the following HTML
<p>
Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!
</p> |
| Code Block |
|---|
{ "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":"jane@emailjohn@email.com", "key_value_collection": { "first_name": "Jane", "agefirst_name":"John", 28 } } ] } |
Example - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{ "mailing_id": 213, "recipients": [ "email@email.com", "..." ], "email_message": { "content_text": "SMS content""age": 34 } }, "addresses": [ { { "from_namerecipient": "My name"jane@email.com", "espkey_connectionvalue_idcollection": 1{ } ] }, "distributionfirst_name": [ { "esp_connection_id": 1,"Jane", "domain": "default", "percentage": 10028 } ], "message_dynamic_fields": { "test": 234, "uid": 32431 }, "disable_unsubscribe": true } |
...
}
}
]
} |
Request Example - Transactional Send - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/transactional_send
| Code Block |
|---|
{
"message_id":45678,
"mailingcampaign_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
...
" ],
"sending_connection_id": 556677,
"disable_unsubscribe": true
} |
Appendix
SMTPs that support Cc and Bcc
MailGun
Amazon SES
MailJet
mySMTP
Oracle Dyn (On Request)
SocketLabs
SparkPost
Sendgrid