Email Message API Methods

Owned by Pratik Upadhyay
Last updated: Jan 21, 2024 by Noam Rotem
10 min read

Table of Contents:

(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

DELETE /api/emails/<Email ID>

Description 

This method deletes an Email/Template.

Response

The response includes deleted email array of fields.

Error codes

  • 400 - Dependency error
  • 403 - Permission error
  • 404 - Email not found/deleted

GET /api/emails/<Email Message ID>

Description 

This method lists a single email/template, including mailings and addresses. Return a single Email/Template

Response Example

GET URL: https://api.ongage.net/<list_id>/api/emails/<email_message_id>

{
 "metadata":
 {
  "error": false
 },
 "payload":
 {
  "id": "2025",
  "type": "email_message",
  "account_id": "26099",
  "list_id": "23939",
  "name": "Email name",
  "description": "",
  "subject": "Email subject",
  "content_html": "Email html content",
  "content_text": "Email text content",
  "unsubscribe_default_link": "1",
  "unsubscribe_success_html": "You have been successfully unsubscribed",
  "unsubscribe_confirmation_html": "",
  "unsubscribe_confirmation_button": "",
  "created": "1416399606",
  "modified": "1416399614",
  "deleted": "0",
  "mailing_id": "111670"
 }
}

Error codes

  • 403 - Permission error
  • 404 - Unauthorized / Email not found

GET /api/emails

Description 

This method fetches a collection of email messages/templates.

Request

type

Optional string - email_message / template / folder

name

Optional string

This is the name of the email message (unrelated to the subject of the message, which is a separate parameter – see below).

parent_id

Optional number - id of folder in which the template is located

subject

Optional string - subject of the email

modified_from

Optional number - from "unix timestamp" in which the email was modified

modified_to

Optional number - from "unix timestamp" in which the email was modified

created_by

Optional number - user id of created

favorite

Optional number - 1 / 0 if email was marked as favorite or not

page

Optional number - number of current page. default 1

page_size

Optional number - size of page. default 50

list_id

Optional number - number of list which this email is associated with

get_tags

Optional boolean - return array of tag ids for each message
e.g., https://api.ongage.net/api/emails?get_tags=1

Response Example

GET URL: https://api.ongage.net/<list_id>/api/emails

The response returns paginated Email results.

{
 "metadata":
 {
  "error": false,
  "total": "2"
 },
 "payload":
 [
  {
   "id": "2008",
   "type": "email_message",
   "account_id": "26099",
   "list_id": "23939",
   "name": "Email name",
   "description": "",
   "subject": "Subject",
   "content_html": "Email html content",
   "content_text": "Email text content",
   "unsubscribe_default_link": "1",
   "unsubscribe_success_html": "You have been successfully unsubscribed",
   "unsubscribe_confirmation_html": "",
   "unsubscribe_confirmation_button": "",
   "created": "1415701181",
   "modified": "1415701181",
   "deleted": "0",
   "mailing_id": null
  },
  {
   "id": "2025",
   "type": "email_message",
   "account_id": "26099",
   "list_id": "23939",
   "name": "Email name",
   "description": "",
   "subject": "Email subject",
   "content_html": "Email html content",
   "content_text": "Email text content",
   "unsubscribe_default_link": "1",
   "unsubscribe_success_html": "You have been successfully unsubscribed",
   "unsubscribe_confirmation_html": "",
   "unsubscribe_confirmation_button": "",
   "created": "1416399606",
   "modified": "1416399614",
   "deleted": "0",
   "mailing_id": "111670"
  }
 ]
}

POST /api/emails

Description 

This method creates a new email message.

Request

type

Required string - The type of item, can be: email_message, template, or folder

list_id

Optional number - The list id to which the email should be saved under

parent_id

Optional number - The folder which this item will reside, specify "0" for root folder.

preheader

Optional string - Pre-header for the Email

name

Required string - The name for new item

description

Required string - The description for new item

subject

Required string - The subject of new item

content_html

Required string - The HTML content

content_text

Required string - The plain text content

content_import_url

Optional string - Import zip file that contain html and images. when passing content url, "content_text" and "content_html" fields will be overwritten by the file content.

favorite

Optional 1 or 0 - Favorite on/off

no_wysiwyg

Optional 1 or 0 - Use ckeditor on/off

language_iso

Optional string - The language of this item (en/es/it/fr/...)

header_template_id

Optional number - Indicate template_id to insert a template to the top of this email message. (Note: Any changes you make to this template will apply up until the email message is sent)

footer_template_id

Optional number - Indicate template_id to insert a template to the bottom of this email message. (Note: Any changes you make to this template will apply up until the email message is sent)

addresses

Optional array of arrays:

*from_name: From name

*from_address: From address

*reply_address: Reply address

*esp_connection_id

tag_ids

Optional array of numbers - email tag IDs. In order to create a new email tag, please use POST api/email_tag method.

unsubscribe_default_link

Optional boolean - An unsubscribe link is mandatory for each email. If you set the default unsubscribe link to false, you must define an unsubscribe link yourself in the content_html part.

Important :

In case this field is not given at all in your request - the "unsubscribe_default_link" from your list default settings will apply.

unsubscribe_confirmation_html

Optional string- Unsubscribe confirmation page displayed after pressing the unsubscribe link.

Important :

In case this field is not given at all in your request - the "unsubscribe_confirmation_html" from your list default settings will apply (in case it was set).

unsubscribe_confirmation_button

Optional string - The text on the Unsubscribe confirmation button. The confirmation button will appear at the bottom of the page, centralized.

Important :

In case this field is not given at all in your request - the "unsubscribe_confirmation_button" from your list settings will apply (in case your set it AND in case "unsubscribe_confirmation_html" is set as well).

unsubscribe_success_html

Optional string - Unsubscribe success page displayed after a successful unsubscribe

Important :

In case this field is not given at all in your request - the "unsubscribe_success_html" from your list settings will apply (in case it was set)

frequency_active

Optional boolean - Activate emails frequencies

Important :

1. In case this field was not provided - the "frequency_active" from your list settings will apply (in case it was set)

ONLY if "unsubscribe_success_html" was given OR if "unsubscribe_success_html" was applied from the list :

2. If "frequency_active" is applied from the list settings level, it will automatically apply your list settings of "frequency_html", "frequencies" and "frequency_button".

frequency_html

Optional string - must be provided if "frequency_active" is set to true. The text that will be displayed before the frequencies select box

Important :

"frequency_active" must be provided or else this field will be applied according to you list settings.

frequencies

Optional array of objects - must be provided if "frequency_active" is set to true.

*active: true/false

*title: "string"

*value: "Frequency1"/"Frequency2"/"Frequency3"

Important :

"frequency_active" must be provided or else this field will be applied according to your list settings

link_query_params

Optional Object - Keys and values of link-query parameters that will be added automatically to all links in the email

Important :

In case this field is not given at all in your request - the "link_query_params" from your list settings will apply (in case it was set)

Example 

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

{
    "type": "email_message",
    "name" :"My first email",
    "subject" :"My first email",
    "content_html" :"<html><body>My first email</body></html>",
    "content_text": "testing",
    "addresses": [
      {
        "from_name": "My name",
        "from_address": "my@address.com",
        "reply_address": "my@address.com",
        "esp_connection_id": 1
      },
      {
        "from_name": "My name",
        "from_address": "my@address.com",
        "reply_address": "my@address.com",
        "esp_connection_id": 2
      }
    ],
    "tag_ids": [ 1001, 1002 ],
    "unsubscribe_default_link": true,
    "unsubscribe_confirmation_html" : "<p>Are you sure you want to unsubscribe?</p>",
    "unsubscribe_confirmation_button" : "Unsubscribe",
    "unsubscribe_success_html": "<p>you have been successfully unsubscribe</p>",
    "frequency_active": true,
    "frequency_html": "<p>Choose how frequent would you like to receive our email</p>",
    "frequencies" : [
        {
            "active":true,
            "title":"Weekly",
            "value":"Frequency1"
        },
        {
            "active":true,
            "title":"Twice a month",
            "value":"Frequency2"
        },
        {
            "active":true,
            "title":"Monthly",
            "value":"Frequency3"
        }
    ],
    "link_query_params": {
       "campaign": "my_campaign_identifier",
       "custom_key": "custom_value"
    }
  }

Response

The response includes a newly created email array of fields.

Error codes

  • 403 - Permission error
  • 406 - Account setup is required

PUT /api/emails/<Email Message ID>

Description 

This method updates an existing email.

Request

type

Required string - The type of item, can be: email_message, template, or folder

list_id

Optional number - The list id to which the email should be saved under

parent_id

Optional number - The folder which this item will reside, specify "0" for root folder.

preheader

Optional string - Pre-header for the Email

name

Required string - The name for new item

description

Required string - The description for new item

subject

Required string - The subject of new item

content_html

Required string - The HTML content

content_text

Required string - The plain text content

content_import_url

Optional string - Import zip file that contains html and images. when passing the content URL, "content_text" and "content_html" fields will be overwritten by the file content.

favorite

Optional 1 or 0 - Favorite on/off

no_wysiwyg

Optional 1 or 0 - Use ckeditor on/off

language_iso

Optional string - The language of this item (en/es/it/fr/...)

header_template_id

Optional number - Indicate template_id to insert a template to the top of this email message. (Note: Any changes you make to this template will apply up until the email message is sent)

footer_template_id

Optional number - Indicate template_id to insert a template to the bottom of this email message. (Note: Any changes you make to this template will apply up until the email message is sent)

addresses

Optional array of arrays:

*from_name: From name

*from_address: From address

*reply_address: Reply address

*esp_connection_id

tag_ids

Optional array of numbers - email tag IDs. In order to create a new email tag, please use POST api/email_tag method.

unsubscribe_default_link

Optional boolean - An unsubscribe link is mandatory for each email. If you set the default unsubscribe link to false, you must define an unsubscribe link yourself in the content_html part.

Important :

In case this field is not given at all in your request - the "unsubscribe_default_link" from your list default settings will apply.

unsubscribe_confirmation_html

Optional string- Unsubscribe confirmation page displayed after pressing the unsubscribe link.

Important :

In case this field is not given at all in your request - the "unsubscribe_confirmation_html" from your list default settings will apply (in case it was set).

unsubscribe_confirmation_button

Optional string - The text on the Unsubscribe confirmation button. The confirmation button will appear at the bottom of the page, centralized.

Important :

In case this field is not given at all in your request - the "unsubscribe_confirmation_button" from your list settings will apply (in case your set it AND in case "unsubscribe_confirmation_html" is set as well).

unsubscribe_success_html

Optional string - Unsubscribe success page displayed after a successful unsubscribe

Important :

In case this field is not given at all in your request - the "unsubscribe_success_html" from your list settings will apply (in case it was set)

frequency_active

Optional boolean - Activate emails frequencies

Important :

1. In case this field was not provided - the "frequency_active" from your list settings will apply (in case it was set)

ONLY if "unsubscribe_success_html" was given OR if "unsubscribe_success_html" was applied from the list :

2. If "frequency_active" is applied from the list settings level, it will automatically apply your list settings of "frequency_html", "frequencies" and "frequency_button".

frequency_html

Optional string - must be provided if "frequency_active" is set to true. The text that will be displayed before the frequencies select box

Important :

"frequency_active" must be provided or else this field will be applied according to you list settings.

frequencies

Optional array of objects - must be provided if "frequency_active" is set to true.

*active: true/false

*title: "string"

*value: "Frequency1"/"Frequency2"/"Frequency3"

Important :

"frequency_active" must be provided or else this field will be applied according to your list settings

link_query_params

Optional Object - Keys and values of link-query parameters that will be added automatically to all links in the email

Important :

In case this field is not given at all in your request - the "link_query_params" from your list settings will apply (in case it was set)

Example 

PUT URL: https://api.ongage.net/<list_id>/api/emails/<email_message_id>

  {
    "type": "email_message",
    "content_html" :"<html><body>My first email</body></html>",
    "content_text": "testing",
    "addresses": [
      {
        "from_name": "My name",
        "from_address": "my@address.com",
        "reply_address": "my@address.com",
        "esp_connection_id": 1
      },
      {
        "from_name": "My name",
        "from_address": "my@address.com",
        "reply_address": "my@address.com",
        "esp_connection_id": 2
      }
    ],
    "tag_ids": [ 1001, 1002 ],
    "unsubscribe_default_link": true,
    "unsubscribe_confirmation_html" : "<p>Are you sure you wannt to unsubscribe?</p>",
    "unsubscribe_confirmation_button" : "Unsubscribe",
    "unsubscribe_success_html": "<p>you have been successfully unsubscribe</p>",
    "frequency_active": true,
    "frequency_html" "<p>Choose how frequent would you like to receive our email</p>",
    "frequencies" : [
        {
            "active":true,
            "title":"Weekly",
            "value":"Frequency1"
        },
        {
            "active":true,
            "title":"Twice a month",
            "value":"Frequency2"
        },
        {
            "active":true,
            "title":"Monthly",
            "value":"Frequency3"
        }
    ],

    "link_query_params": {
       "campaign": "my_campaign_identifier",
       "custom_key": "custom_value"
    }

Overwrite existing email

In case the email used in campaign that already launched, it will create a copy instead of updating the existing one. If you want to overwrite it, add overwrite = TRUE parameter to request payload.

Response

The response includes an updated email's array of fields. It might also include a warning message.

Error codes

  • 403 - Permission error
  • 404 - Email not found/deleted
  • 500 - General error

PUT /api/emails/<Email Message ID>/copy

Description 

This method is used to copy email message to another list.

Request

target_list_id

Required number - Specify list id to copy the email message to.

target_list_ids

Required number - Specify list ids to copy the email message to.

Response

The response returns copied email updated details

Example

PUT URL: https://api.ongage.net/<list_id>/api/emails/<email_message_id>/copy

  { "target_list_id" : "12345" }

PUT /api/emails/<Email Message ID>/favourite

Description 

This method is used to toggle favorite.

Response

The response returns single row with updated details.

Error codes

  • 403 - Permission error
  • 404 - Email not found

PUT /api/emails/<Email Message ID>/move

Description 

This method is used to move or rename an email/template in library.

Request

parent_id

Required number - The folder which this item will reside, specify "0" for root folder.

name

Required string - Item name

Example

PUT URL: https://api.ongage.net/<list_id>/api/<email_message_id>/move

  { "parent_id": 1, "name": "Dazzling email" }

Error codes

  • 403 - Permission error
  • 404 - Email not found / deleted