Send Email API

The SendEmail API can be used to send out transactional emails from outside the Envoke user interface.

Marcel Ursprung avatar
Written by Marcel Ursprung
Updated over a week ago

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.

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.

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"
    }
]
Did this answer your question?