Skip to content
MailPush Docs

Send an email

POST https://api.mailpush.app/v1/emails

Headers

Section titled “Headers”
Header Required Description
Authorization Yes Bearer followed by an API key.
Content-Type Yes application/json.
Idempotency-Key No 1 to 256 visible ASCII characters. A second request with the same key returns the first email’s id and sends nothing. See Idempotency.

Body parameters

Section titled “Body parameters”
Parameter Type Required Description
from string Yes The sender, on a domain verified by your account. hello@example.com or Acme <hello@example.com>.
to string or string[] Yes One address or a list.
cc string or string[] No One address or a list.
bcc string or string[] No One address or a list.
reply_to string No The address replies go to.
subject string Yes, unless template is given One line, 998 characters at most. With a template, it replaces the template’s subject.
html string One of html, text, template The HTML body.
text string One of html, text, template The plain text body. When you only give html, MailPush builds the text version from it.
template string One of html, text, template The alias or the id of a published template. Cannot be combined with html or text.
data object No The values of the template’s variables. Only with template.
headers object No Extra headers, such as { "X-Campaign": "welcome" }. Names set by other fields or by MailPush, like From, Subject or DKIM-Signature, are refused.
tracking object No { "opens": boolean, "clicks": boolean }. Turns open and click tracking on or off for this email. A field left out follows the sending domain, which tracks both unless you turned them off.

to, cc and bcc hold 50 recipients at most in total. The whole request is 10 MB at most.

Response

Section titled “Response”

200 OK with the id of the email.

{ "id": "em_4b9b3c1f0a2e7d5c9e8f1a2b" }

The email is stored and queued. Delivery happens afterwards: read it with GET /v1/emails/:id.

Example

Section titled “Example”
Terminal window
curl https://api.mailpush.app/v1/emails \
  -H "Authorization: Bearer $MAILPUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@example.com>",
    "to": ["customer@example.org", "billing@example.org"],
    "reply_to": "support@example.com",
    "subject": "Your order is ready",
    "html": "<p>Hello, your order is waiting for you.</p>"
  }'
const { id } = await mailpush.emails.send({
  from: "Acme <hello@example.com>",
  to: ["customer@example.org", "billing@example.org"],
  replyTo: "support@example.com",
  subject: "Your order is ready",
  html: "<p>Hello, your order is waiting for you.</p>",
});

With a template:

Terminal window
curl https://api.mailpush.app/v1/emails \
  -H "Authorization: Bearer $MAILPUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@example.com>",
    "to": "customer@example.org",
    "template": "order-confirmation",
    "data": { "firstName": "Camille", "order": { "id": "1234" } }
  }'

Errors

Section titled “Errors”
Status Code When
400 invalid_request A required field is missing or has the wrong type, template is combined with html or text, or tracking holds something else than opens and clicks as booleans.
400 invalid_email An address is not valid, the subject spans several lines, or a header is refused.
401 missing_api_key, invalid_api_key No key, or a wrong or revoked one.
413 payload_too_large The request is larger than 10 MB.
422 domain_not_verified The domain of from is not verified by your account.
422 template_not_found Your account has no template with that alias or id.
422 template_not_published The template has no published version yet.
422 missing_template_data data lacks a variable the template prints. The message lists the names.
429 rate_limited More than 10 requests in a second with this key.
429 daily_quota_exceeded The account reached its recipients for the day.

See Errors for the format and what to do for each code.