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 <recipient1@example.com>",
        "Recipient 2 <recipient2@example.com>"
    ],
    "cc": [
        "CC Recipient 1 <cc-recipient1@example.com>"
    ],
    "bcc": [
        "BCC Recipient 1 <bcc-recipient1@example.com>"
    ],
    "sender": "Sender <sender@example.com>",
    "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 <reply-to-user@example.com>"
        }
    ],
    "attachments": [
        {
            "filename": "test.txt",
            "data": "VGhpcyBpcyBhIHRlc3QgZmlsZQ==",
            "mimetype": "text/plain"
        }]
}
EOF

<?php
$data = [
    "to" => ["Recipient 1 <recipient1@example.com>"],
    "sender" => "Sender <sender@example.com>",
    "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 <recipient1@example.com>"
    ],
    "sender": "Sender <sender@example.com>",
    "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 <test@example.com>": [
        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 <recipient@example.com>" ] ] }, "cc": { "type": "array", "title": "An array of CC recipients", "maxItems": 255, "items": { "type": "string", "format": "email", "title": "Recipient mailbox" }, "examples": [ [ "Recipient <cc-recipient@example.com>" ] ] }, "bcc": { "type": "array", "title": "An array of BCC recipients", "maxItems": 255, "items": { "type": "string", "format": "email", "title": "Recipient mailbox" }, "examples": [ [ "Recipient <bcc-recipient@example.com>" ] ] }, "sender": { "type": "string", "format": "email", "title": "The sender address", "examples": [ "Sender <sender@example.com>" ] }, "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 <reply-to-user@example.com>" }] ] }, "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 <recipient@example.com>" ], "cc": [ "CC recipient <cc-recipient@example.com>" ], "bcc": [ "BCC recipient <bcc-recipient@example.com>" ], "sender": "Sender <sender@example.com>", "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 <reply-to-user@example.com>" }], "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 <recipient@example.com> and recipient@example.com are valid.