The SendEmail API can be used to send out transactional emails from outside the Envoke user interface and associate individual emails to messages to report on for delivery statistics.
Various sized batches of emails can be sent to the API for processing. Each batch will be linked to a message which will be used for reporting purposes.
This API takes an array of “email” objects, each with its own “message_html” for content.
Most “email” object fields are optional with the exception of “campaign_name” and “to_email”. The “to_email” field is always required unless a “contact_id” is supplied.
You can't send an email by providing a template or message ID to the API. You need to supply the raw HTML to the API using the message_html field.
Endpoint
Tester
Fields
contact_id (optional)
Type: Integer
This is the id of an existing Envoke contact. If provided the contact values from the existing contact record will be used, unless “to_email” is also filled in which case it will use that value
to_name (optional - will use “to_email” if not set)
Type: String
This is the To: name email header field.
to_email (required unless contact_id is filled)
Type: String
This is the email address the API will send the message to. This will create a new contact if en existing contact with same email address can’t be found.
IMPORTANT: If an existing contact is not found this will create a new contact but with consent “Not Provided” so the email will not be sent. To use this first create the contact with appropriate consent and use the contact_id option or exact match to the email address of the newly created contact.
from_name (optional - will use default account from name)
Type: String
This is the From: name header field.
from_email (optional - will use default account from email)
Type: String
This is the From: email header field.
reply_name (optional – will use default account from name)
Type: String
This is the Reply-To: name header field.
reply_email (optional – will use default account from email)
Type: String
This is the Reply-To: email header field.
campaign_name (required)
Type: String
This is will create a new message or use a message with the same name.
campaigngroup_name (optional)
Type: String
This will add the message to an existing message group matching the name or create a new group.
campaigngroup_id (optional)
Type: Integer
This will add the message to the message group matching the id.
message_html (optional)
Type: String
This is the message HTML body content
message_text (optional)
Type: String
This is the message Text body content
message_subject (optional)
Type: String
This is the Subject: header field.
track_unsubscribes (optional – default TRUE)
Type: Boolean
If true this will attach the unsubscribe link to the message body. This is not supported with the "mandatory_message" enabled field.
track_opens (optional – default TRUE)
Type: Boolean
If true this will track email opens.
track_clicks (optional – default TRUE)
Type: Boolean
If true this will track link clicks.
merge_fields (optional – default TRUE)
Type: Boolean
If true this will merge contact fields into the message body.
mandatory_message (optional – default FALSE)
Type: Boolean
If true this will mark the message as a mandatory communication which bypasses the regular CASL consent checks. This field by itself won't make the message mandatory, you also need to enable this feature on your account. Contact support to enable this.
Do not turn off "track_unsubscribes" when enabling the mandatory message field, it's required that you show the unsubscribe link with mandatory messages.
mandatory_reason (optional)
Type: String
If this message is marked as a mandatory communication (see mandatory_message flag above) then please provide a reason why it's mandatory. This will be shown to the contact as part of the unsubscribe footer.
API Limits
The maximum recommended batch size is 100 emails per batch.
Campaign options
These are set when sending the first email with a new message name, and can’t be updated after the first email via the API, instead use a different message name, or change some of these setting via the UI.
campaign_name
campaigngroup_name
track_unsubscribes
track_clicks
track_opens
merge_fields
Campaign options if you have the mandatory communication feature enabled.
mandatory_message
mandatory_reason
Contact options
These are set when sending the first email to a contact, but can be update with the next send.
to_name
to_email
from_email
from_name
reply_email
reply_name
Message options
These are not stored on the server but instead just used for this request
message_html
message_subject
Message_text
JSON request data structure
{
"SendEmails": [
{
"EmailDataArray": [
{
"email": [
{
"contact_id": "int",
"campaign_id": "int",
"campaigngroup_id": "int",
"campaign_name": "string",
"campaigngroup_name": "string",
"to_email": "string",
"to_name": "string",
"from_email": "string",
"from_name": "string",
"reply_email": "string",
"reply_name": "string",
"message_subject": "string",
"message_html": "string",
"message_text": "string",
"track_unsubscribes": "boolean",
"track_opens": "boolean",
"track_clicks": "boolean",
"merge_fields": "boolean"
"mandatory_message": "boolean",
"mandatory_reason": "string"
},
{
"contact_id": "int",
"campaign_id": "int",
"campaigngroup_id": "int",
"campaign_name": "string",
"campaigngroup_name": "string",
"to_email": "string",
"to_name": "string",
"from_email": "string",
"from_name": "string",
"reply_email": "string",
"reply_name": "string",
"message_subject": "string",
"message_html": "string",
"message_text": "string",
"track_unsubscribes": "boolean",
"track_opens": "boolean",
"track_clicks": "boolean",
"merge_fields": "boolean"
"mandatory_message": "boolean",
"mandatory_reason": "string"
}
]
}
]
}
]
}JSON response data structure
[
{
"result_type": "int",
"result_value": "boolean",
"result_data": [
{
"response": [
{
"request_type": "string",
"request_id": "string",
"response_type": int,
"response_value": "boolean",
"response_data": "int",
"response_text": "string"
},
{
"request_type": "string",
"request_id": "string",
"response_type": int,
"response_value": "boolean",
"response_data": "int",
"response_text": "string"
}
]
}
],
"result_text": "string"
}
]
Example request
{
"SendEmails": [
{
"EmailDataArray": [
{
"email": [
{
"to_email": "email1@domain.com",
"to_name": "email1",
"from_email": "info@envoke.com",
"from_name": "Envoke Info",
"reply_email": "noreply@envoke.com",
"reply_name": "No reply",
"message_subject": "This is an API send - 1",
"message_html": "<b>This is bold</b> This is not bold, {email}, <a href='https://envoke.com'>Envoke</a>",
"message_text": "This is a text message"
},
{
"to_email": "email2@domain.com",
"to_name": "email2",
"from_email": "info@envoke.com",
"from_name": "Envoke Info",
"reply_email": "noreply@envoke.com",
"reply_name": "No reply",
"campaign_name": "API TEST MESSAGE 123",
"campaigngroup_name": "API TEST MESSAGE GROUP 123",
"message_subject": "This is an API send - 1",
"message_html": "<b>This is bold</b> This is not bold, {email}, <a href='https://envoke.com'>Envoke</a>",
"message_text": "This is a text message",
"track_unsubscribes": false,
"track_opens": false,
"track_clicks": false,
"merge_fields": false
"mandatory_message": true,
"mandatory_reason": "membership requirement"
}
]
}
]
}
]
}
Example response
[
{
"result_type": "0",
"result_value": "true",
"result_data": [
{
"response": [
{
"request_type": "send",
"request_id": "email1@domain.com",
"response_type": 0,
"response_value": "true",
"response_data": "123456",
"response_text": "TRUE: Request successful, email sent to: email1@domain.com"
},
{
"request_type": "send",
"request_id": "email2@domain.com",
"response_type": 0,
"response_value": "true",
"response_data": "123457",
"response_text": "TRUE: Request successful, email sent to: email2@domain.com"
}
]
}
],
"result_text": "TRUE: Request successful, 2 email(s) sent"
}
]