The SendEmail API can be used to send out transactional emails from outside the Envoke user interface and associate individual emails sends 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.

Endpoint

https://e1.envoke.com/api/v4legacy/send/SendEmails

Tester

https://e1.envoke.com/api/v4legacy/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.

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

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"
                        },
                        {
                            "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"
                        }
                    ]
                }
            ]
        }
    ]
}

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

                        }

                    ]

                }

            ]

        }

    ]

}

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?