HTTP mail resource

Overview

This endpoint allows you to send email over Sendmachine’s Web API.

Send mail

Request

POST /mail/send

Request body

{
    "personalization": [{
        "to": [{
            "email": "example@recipient.com"
            }],
        "macros": {
            "FIRST_NAME": "John",
            "LAST_NAME": "Doe"
        }
    }],
    "message": {
        "from": {
            "email": "confirmed@email-address.com"
        },
        "subject": "Sample subject",
        "template_id": "tpl_id"
    }
}

Success response

{
    "status": "sent",
    "sent": 10
}

Full parameter list

{
    "personalization": [{
        "to": [{
            "email": "", (*)
            "name": ""
        }],
        "cc": [{
            "email": "",
            "name": ""
        }],
        "bcc": [{
            "email": "",
            "name": ""
        }],
        "subject": "",
        "headers": {},
        "macros": {},
        "metadata": {}
        }],
   "message": {
        "headers": {}, (**)
        "from": {
            "email": "", (*)
            "name": ""
        },
        "reply_to": {
            "email": "",
            "name": ""
        },
        "subject": "", (**)
        "template_id": "",
        "body_text": "",
        "body_html": ""
    },
    "message_type": "",
    "campaign_name": "",
    "open_tracking": "",
    "click_tracking": ""
}

Note

  • Properties marked with * are mandatory and can’t be empty

  • Properties marked with ** may be overwritten by the personalization object

Personalization

When sending email, the various metadata about the message are contained within an array called personalizations. Think of the personalizations section of the request body like the envelope of a letter: the fields defined within personalizations apply to each individual email. Like an envelope, personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled. For example, you can define what headers you would like to include, and any substitutions or custom arguments you would like to be included with the email.

  • To: email - Recipient’s email address

  • To: name - Recipient’s name

  • Cc: email - Message CC (carbon copy) email

  • Cc: name - Message CC (carbon copy) name

  • Bcc: email - Message BCC (blind carbon copy) email

  • Bcc: name - Message BCC (blind carbon copy) name

  • Subject - Message subject (required if global subject was not provided)

  • Headers - An object containing key/value pairs of header names and the value to substitute for them

  • Macros - These macros will apply to the content of your email. Also see: Smtp Macros documentation

  • Metadata - Provided metadata content will be sent alongside webhook request if any

Message

  • Headers - Global message headers. An object containing key/value pairs of header names and the value to substitute for them. Some keys in the object may be overridden by the personalization header

  • From: email - From email address

  • From: name - From name

  • Reply to: email - Reply to email

  • Reply to: name - Reply to name

  • Subject - Global message subject (required if specific recipient subject was not provided)

  • Template id - Message template id (required if body_html parameter was not provided)

  • Body text - Message body text

  • Body html - Message body html (required if template id was not provided)

Message type - Message type: tranzactional/campaign

Campaign name - Message name - for transactional use

Open tracking - Specifies whether opens should be tracked or not true/false

Click tracking - Specifies whether clicks should be tracked or not true/false

Note

  • When building the personalization object keep in mind that duplicate recipients in the same personalization will be ignored.

Limitations

  • The total size of your email must be less than 20MB.

  • The total number of recipients must be less than 1000. This includes all recipients defined within the to, cc, and bcc parameters, across each object that you include in the personalizations array.

  • The total number of personalizations must be less than 100.

  • The to.name, cc.name, and bcc.name personalizations cannot include either the ; or , characters.

Reserved data

When building the message data array please note that there are some reserved attributes for various properties.

  • Reserved macros: date, year, email_to, unsub_link

  • Reserved headers: to, cc,bcc, reply-to, date, message-id, return-path ,received, sender, dkim-signature, domainkey-signature, delivered-to, authentication-results, received-spf, content-type, content-transfer-encoding

Authentification

curl -X "POST" "https://api.sendmachine.com/mail/send" -u "API_KEY:API_PASSWORD" -H "Content-Type: application/json" -d "[YOUR DATA HERE]"

You must authenticate every API request to send mail by including an Authorization header.

Response

If the request is successful, the API will return a 202 OK status code meaning that the request has been accepted for processing, but the processing has not been completed.

The response body will contain a JSON object with the following properties:

{
    "status": "sent",
    "sent": 10
}

PHP Code sample

Send a message to a specific recipient, with custom data:

<?php

$data = array(
    'personalization' => array(
        array(
            'to' => array(
                array(
                    'email' => 'example@recipient.com',
                )
            ),
            'macros' => array(
                'FIRST_NAME' => 'John',
                'LAST_NAME' => 'Doe',
            ),
        ),
    ),
    'message' => array(
        'from' => array(
            'email' => 'confirmed@email-address.com',
        ),
        'template_id' => 'tpl_id',
        'subject' => 'Sample subject'
    ),
);

$jsondata = json_encode($data);

$ch = curl_init ('https://api.sendmachine.com/mail/send');

curl_setopt($ch, CURLOPT_USERPWD, 'API_KEY:API_PASSWORD');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsondata);

$response = curl_exec($ch);

Response status and codes

  • 202: sent

  • 400:

    • notemplate

    • email_too_big

    • pers_limit_reached

    • send_limit_reached

    • rating_dropped

    • sendingspeed_exceeded

    • invalid_json

    • missing_recipient

    • invalid_recipient

    • missing_replyto

    • invalid_replyto

    • missing_sender

    • invalid_sender

    • missing_subject

    • invalid_subject

    • new_sender

    • confirm_sender

    • disallowed_domain

    • missing_personalization

    • missing_body

    • invalid_type

    • invalid_headers

    • invalid_campaign_name

    • invalid_field_value

  • 401: denied

  • 500: error

  • 503: test_email_limit_hit