Send an email, a batch, or one for later

POST /v1/emails takes one email and answers with its id; everything after it is on the email's page.

Read the sending guide
const email = await minket.emails.send({
  from: "receipts@mail.fernbank.example",
  to: "rui.okafor@example.com",
  subject: "Your receipt for order 10452",
  html: "<p>Thanks, Rui. Your receipt is attached.</p>",
  attachments: [
    { id: "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b" },
  ],
  tags: [{ name: "order", value: "10452" }],
});
curl https://api.minket.com/v1/emails \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-10452" \
  -d '{
    "from": "receipts@mail.fernbank.example",
    "to": "rui.okafor@example.com",
    "subject": "Your receipt for order 10452",
    "text": "Thanks, Rui. Your receipt is attached.",
    "attachments": [
      { "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b" }
    ],
    "tags": [{ "name": "order", "value": "10452" }]
  }'

In the console

  • QueuedYour receipt for order 10452rui.okafor@example.com18:00:00
The status moves as events arrive.

Retry with the same key and get the same answer

An idempotency key holds for 24 hours, and the TypeScript SDK puts one on every send that has none.

Same key, same body
the stored answer, idempotent_replay: true
Same key, other body
422 invalid_idempotent_request
Same key, still running
409 concurrent_idempotent_requests

A batch of 100, one answer each

POST /v1/emails/batch checks every item on its own, so one bad address costs one email.

{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5d",
      "status": "queued"
    },
    {
      "index": 1,
      "error": { "code": "validation_error", "retryable": false }
    }
  ],
  "accepted": 1,
  "rejected": 1
}
The answer to a batch of two

Schedule up to 30 days ahead

Set scheduled_at to a time or to words read in UTC, then move or cancel it until it goes.

{ "scheduled_at": "tomorrow at 9am" }
Scheduled in words

Attachments inline, by reference or by URL

Up to 20 on one email, within 40 MB for the whole message.

Three ways to attach a file
FormUp toHow
Inline4 MBcontent in the request
By reference25 MBan id from POST /v1/attachments, reused
By URL25 MBpath, fetched over https as it sends

No email goes out twice

When a send's outcome is unclear, the email is marked failed with outcome_unknown instead of going out again.

sent
accepted for delivery
delivered
the receiving server took it
failed
with a reason you can act on

Test keys deliver nothing

A minket_test_ key accepts, renders and stores mail and plays its events, 2 seconds apart.

Sandbox

Test mode
RecipientEvents played
delivered@minket.testemail.sent, email.delivered
bounced@minket.testemail.sent, email.bounced
complained@minket.testemail.sent, email.delivered, email.complained
delayed@minket.testemail.sent, email.delivery_delayed, email.delivered

Templates, streams and SMTP

Questions

What if an address is suppressed?

The email is accepted and reported with email.suppressed, and the other recipients still get it.

Can marketing mail go to many?

One recipient per marketing email, so each unsubscribe link belongs to one person.

How many recipients per email?

Up to 50 across to, cc and bcc.