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,
"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).
...
| 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 /api/notify_transactions
| Warning |
|---|
|
| 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": "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
...
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"
}
]
} |
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:
| Code Block |
|---|
{
"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/notifytransactional_transactionssend
| Code Block |
|---|
{
"mailingmessage_id": 2134567,
"recipients": [ "email@email.com", "..." ],
"campaign_id": 213,
"emailsending_messageconnection_id": 168, // `email_message_id` will override '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 |
|---|
{ "mailing1234 } |
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": [ "email@emailjohn@email.com", "jane@email...com" ], "emailsending_connection_messageid": { "subject": "Email Subject"1234, "content_html": "<html>Content HTML</html>", "content_text": "Content Text", "addresses": message_dynamic_fields_per_recipient":[ { "from_name": "My name", "from_address"recipient": "my@addressjohn@email.com", "reply_address": "my@address.com", "espkey_connectionvalue_idcollection": 1{ } ] }, "distribution": [ { "esp_connection_id": 2,first_name":"John", "domain": "default", "percentage": 34 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, { "recipientsrecipient": [ "john@emailjane@email.com", "jane@email.com" ], "emailkey_value_messagecollection": { "subject": "Email Subject", "contentfirst_htmlname": "<html><p>Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!</p></html>",Jane", "content_textage": "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 28 } } ] } |
Request Example - Transactional Send - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/transactional_send
| Code Block |
|---|
{
"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
| 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
} |
Request Example - Embedded content - 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}}% "age": 34until {{expiration_date}}</p>", "addresses": { } }, "from_name": "John Doe", { "recipientfrom_address": "jane@emailjohn@doe.com", "keyreply_value_collectionaddress": {"john@doe.com" }, "firstcampaign_nameid": "Jane"213, "recipients": [ "email@email.com", "..." ], "agesending_connection_id": 281234, "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
| Code Block |
|---|
{
"mailing_id": 213,
"recipients": [ "email@email.com", "..." ],
"email_message": {
"subject": "Email Subject",
"content_html": "<html>Content HTML</html>",
"content_text": "SMSContent contentText",
"addresses": [
{
"from_name": "My name",
"from_address": "my@address.com",
{ "fromreply_nameaddress": "My namemy@address.com",
"esp_connection_id": 1
}
]
},
"distribution": [
{
"esp_connection_id": 12,
"domain": "default",
"percent": 100
}
],
"message_dynamic_fields": { "test": 234, "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 |
|---|
Request Example - Notify Transactions - 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": { "mailing_idsubject": "Email 213Subject", "recipientscontent_html": [ "email@email.com", "..." ], "<html><p>Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!</p></html>", "emailcontent_message_idtext": 168, // `email_message_id` will override 'email_message' collection "check_status": "1","Hello {{first_name}} and congratulations on your birthday, you are {{age}} years old!", "check_suppressionaddresses": "1", [{ "emailfrom_messagename": {"My name", // 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":[ "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":"john@emailjane@email.com", "key_value_collection": { "first_name": "John",Jane", "age": 28 } } ] } |
Request Example - Notify Transactions - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/notify_transactions
| Code Block |
|---|
{ "age"mailing_id": 34 } }, { 213, "recipientrecipients": [ "jane@emailemail@email.com", "..." ], "keyemail_value_collection": { message": { "firstcontent_nametext": "JaneSMS content", "addresses": [ { "agefrom_name": 28"My name", "esp_connection_id": 1 } } } ] } |
Request Example - Transactional Send - Using SMS message content
POST URL: https://api.ongage.net/<list_id>/api/transactional_send
| Code Block |
|---|
{] }, "message_iddistribution":45678, [ { "campaignesp_connection_id": 2131, "recipientsdomain": [ "email@email.comdefault", "...percent": 100 } ], "sendingmessage_connection_iddynamic_fields": { "test": 234, "uid": 55667732431 }, "disable_unsubscribe": true } |
Appendix
SMTPs that support Cc and Bcc
MailGun
Amazon SES
MailJet
mySMTP
Oracle Dyn (On Request)
SocketLabs
SparkPost
Sendgrid