Transactional Mailing API Methods

Owned by Pratik Upadhyay
Last updated: Jun 12, 2024 by Stepin\ Shashin Petel
12 min read

Table of Contents:

Intro

The Transactional API gives you access to all your transactional mailing campaigns in your account.

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

(info) 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", "..." ]
}

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

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

(warning) 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"
   }
  ]
}

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

Request Example - Using Excluded Segment in Transactional campaign

POST URL: https://api.ongage.net/<list_id>/api/transactional/send
Example below where we used two Exclude segments and sent to three recipients. One of those three recipients was part of one of the excluded segments and it was excluded as can be seen in response.  

Request: 
{
     "message_id": 1111111,
     "campaign_id": 1122334455, 
     "excluded_segment_ids": [22222222, 5555555555],
     "recipients": ["samplea@domain.com", "sample2@domain.com", "sample3@domain.com"],
     "sending_connection_id":99999
}
  
Response: 
{
"metadata": {
"error": false
},
"payload": {
"total": 3,
"success": 2,
"failed": 1,
"suppressed": 0,
"not_active": 0,
"queued": 0,
"failed_emails": {
"sample1@domain.com": "Excluded",
}
}
}


Appendix

SMTPs that support Cc and Bcc

  • SparkPost