How sending works

POST /v1/emails answers as soon as the email is stored. Signing and delivery happen afterwards, one recipient at a time.

From request to inbox

1. The API checks the request, stores the email and returns its id. The email is queued.
2. MailPush signs the message with the DKIM key of your domain. The email becomes processed, and each recipient in to, cc and bcc gets its own delivery. If the message cannot be signed, the email is failed and its error field says why.
3. Each delivery is sent to the recipient’s mail server. Its status ends as delivered, bounced, failed or suppressed.

Read the statuses with GET /v1/emails/:id, in the dashboard under Emails, or receive them as webhooks.

Retries

When a mail server refuses an email temporarily (a 4xx answer, a timeout, a rate limit), the delivery is deferred and MailPush tries again after 5, 10, 20 and 40 minutes, then 1, 2, 4 and 8 hours, then every 8 hours. After 72 hours it gives up and the delivery is failed.

A permanent refusal (a 5xx answer) is not retried. The delivery is bounced and keeps the server’s answer in last_response.

Suppressed addresses

MailPush stops writing to an address from your account in two cases:

• the address does not exist (a hard bounce);
• the recipient reported one of your emails as spam.

Later emails to that address are still accepted by the API. The recipient gets the status suppressed and nothing is sent. The list belongs to your account: what other MailPush customers send does not change it.

Idempotency

Networks fail between your server and the API. If you send the same request twice, the email leaves twice, unless the request carries an Idempotency-Key header.

curl https://api.mailpush.app/v1/emails \
  -H "Authorization: Bearer $MAILPUSH_API_KEY" \
  -H "Idempotency-Key: order-1234-confirmation" \
  -H "Content-Type: application/json" \
  -d '{ "from": "hello@example.com", "to": "customer@example.org", "subject": "Order 1234", "text": "Thanks." }'

A second request with the same key returns the id of the first email and sends nothing. The key is 1 to 256 visible ASCII characters and is unique within your account. Build it from what identifies the email, such as an order number, not from a timestamp.

The Node.js SDK adds a key to every call for you.

Test mode

A key that starts with mp_test_ runs every check of a real request, stores the email, and sends nothing.

	Live key	Test key
Request validation and errors	Yes	Yes
Email visible in the dashboard	Yes	Yes, with the status test
Email delivered	Yes	No
Counts against the daily quota	Yes	No
Webhooks	Yes	No
Sender domain	Must be verified	Must be added to the account

Use test keys in automated tests and while your domain is still waiting for DNS.

Next steps

• Limits: recipients per email, requests per second, recipients per day.
• Errors: each error code and what to do about it.