Email Message API Methods
- Pratik Upadhyay
- Stepin\ Shashin Petel
- Noam Rotem
Table of Contents:
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