Send API

Our REST mail delivery API provides email functionality for applications through simple HTTP requests, eliminating the need for SMTP connections while giving you access to our delivery infrastructure.

Examples

Your API key will be the Mail Credential User ID, a hyphen, and the Mail Credential Password. An example API key might look like:

0123456789abcdef0123456789abcdef-123-abcdef0123456789abcdef0123456789abcd

curlPHPPython

curl -XPOST -H "x-api-key: {mail-credential-user}-{mail-credential-pass}" \
  https://send.api.sendamatic.net/send \
  --data-binary @- <<EOF
{
    "to": [
        "Recipient 1 <[email protected]>",
        "Recipient 2 <[email protected]>"
    ],
    "cc": [
        "CC Recipient 1 <[email protected]>"
    ],
    "bcc": [
        "BCC Recipient 1 <[email protected]>"
    ],
    "sender": "Sender <[email protected]>",
    "subject": "Hello world",
    "text_body": "This is a test email",
    "html_body": "<b>This is a test email</b>",
    "headers": [
        {
            "header": "Reply-To",
            "value": "Reply-To User <[email protected]>"
        }
    ],
    "attachments": [
        {
            "filename": "test.txt",
            "data": "VGhpcyBpcyBhIHRlc3QgZmlsZQ==",
            "mimetype": "text/plain"
        }]
}
EOF

<?php
$data = [
    "to" => ["Recipient 1 <[email protected]>"],
    "sender" => "Sender <[email protected]>",
    "subject" => "Hello world",
    "text_body": "This is a test email"
];

$headers = [
    'Content-Type: application/json',
    'x-api-key: {mail-credential-user}-{mail-credential-pass}'
];

$ch = curl_init("https://send.api.sendamatic.net/send");

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

import requests

payload = {"to": [
        "Recipient <[email protected]>"
    ],
    "sender": "Sender <[email protected]>",
    "subject": "Hello world",
    "text_body": "This is a test"
    }

headers = {"x-api-key": "{mail-credential-user}-{mail-credential-pass}"}

r = requests.post("https://send.api.sendamatic.net/send", json=payload, headers=headers)

Output

Example responseRequest schema

HTTP status: 200

An dictionary will be returned with an item for each recipient, along with status code and message ID.

{
    "Recipient <[email protected]>": [
        250,
        "Message Queued (111111-2222-3333-4444-0123456789AB.1)"
    ]
}

A json-schema representation of acceptable JSON data

href="#__codelineno-4-1">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "default": {}, "title": "Sendamatic email send api", "required": [ "to", "sender", "subject" ], "anyOf": [ { "required": ["text_body"] }, { "required": ["html_body"] } ], "properties": { "to": { "type": "array", "title": "An array of recipients", "maxItems": 255, "items": { "type": "string", "format": "email", "title": "Recipient mailbox" }, "examples": [ [ "Recipient <[email protected]>" ] ] }, "cc": { "type": "array", "title": "An array of CC recipients", "maxItems": 255, "items": { "type": "string", "format": "email", "title": "Recipient mailbox" }, "examples": [ [ "Recipient <[email protected]>" ] ] }, "bcc": { "type": "array", "title": "An array of BCC recipients", "maxItems": 255, "items": { "type": "string", "format": "email", "title": "Recipient mailbox" }, "examples": [ [ "Recipient <[email protected]>" ] ] }, "sender": { "type": "string", "format": "email", "title": "The sender address", "examples": [ "Sender <[email protected]>" ] }, "subject": { "type": "string", "minLength": 1, "title": "The email subject", "examples": [ "Hello world" ] }, "text_body": { "type": "string", "minLength": 1, "title": "The text part of the email", "examples": [ "This is a test email" ] }, "html_body": { "type": "string", "minLength": 1, "title": "The html part of the email", "examples": [ "<b>This is a test email</b>" ] }, "headers": { "type": "array", "default": [], "title": "Optional additional headers to send with the email", "items": { "type": "object", "required": [ "header", "value" ], "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 512, "title": "Header name" }, "value": { "type": "string", "minLength": 1, "title": "Header value" } } }, "examples": [ [{ "header": "Reply-To", "value": "Reply-To User <[email protected]>" }] ] }, "attachments": { "type": "array", "default": [], "title": "Attachments", "items": { "type": "object", "required": [ "filename", "data", "mimetype" ], "properties": { "filename": { "type": "string", "minLength": 1, "title": "The file name" }, "data": { "type": "string", "minLength": 1, "title": "Base64 encoded file data" }, "mimetype": { "type": "string", "minLength": 1, "title": "The file mimetype", "examples": [ "application/pdf", "text/plain" ] } } }, "examples": [ [ { "filename": "test.pdf", "data": "--base64-data--", "mimetype": "application/pdf" }, { "filename": "test.txt", "data": "--base64-data--", "mimetype": "text/plain" } ] ] } }, "examples": [{ "to": [ "Recipient <[email protected]>" ], "cc": [ "CC recipient <[email protected]>" ], "bcc": [ "BCC recipient <[email protected]>" ], "sender": "Sender <[email protected]>", "subject": "Hello world", "text_body": "This is a test email", "html_body": "<b>This is a test email</b>", "headers": [{ "header": "Reply-To", "value": "Reply-To User <[email protected]>" }], "attachments": [ { "filename": "test.txt", "data": "VGhpcyBpcyBhIHRlc3QgZmlsZQ==", "mimetype": "text/plain" }] }] }

Errors

Failed requests will return a 4xx or 5xx HTTP status code, with specific details in the reponse body. e.g.

// HTTP 400
{"error": "Invalid MAIL FROM address", "sender": "Sender ", "smtp_code": 501}

// HTTP 400
// Unable to parse request JSON
{"error": "Invalid JSON"}

// HTTP 400
// JSON is well-formed but doesn't match the request schema
{"validation_errors": "'subject' is a required property", "json_path": "$"}

// HTTP 401
// API key is not in the expected format
{"error": "Invalid X-Api-Key"}

// HTTP 403
// API key is invalid, or not associated with a Mail Identity
{"error": "Invalid X-Api-Key"}

Notes

Specifying cc values will overwrite any supplied CC header.
Email display names are optional, e.g. both Recipient <[email protected]> and [email protected] are valid.