POST /api/v1/send sends an email from the mailbox of the key: an order confirmation, a password reset, a receipt. Each recipient gets a copy of their own, and the copy is not saved to Sent.
curl https://mail.example.com/api/v1/send \
-H "Authorization: Bearer mr_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmation" \
-d '{
"to": "anna@example.com",
"subject": "Your order is confirmed",
"text": "Thank you! Order 1042 ships tomorrow.",
"reply_to": "support@example.com"
}'
Fields
| Field | What it is |
|---|---|
to (required) | An address, or a list of up to 50 addresses |
subject (required) | Up to 300 characters |
text | The plain text |
html | The HTML version. With html alone, mailrust builds the text version itself |
from_name | The sender's name; the mailbox's name by default |
reply_to | Where replies go |
At least one of text and html is required, together up to 1 MB.
Answer
202 Accepted: the emails are in the queue and go out within seconds.
{
"ok": true,
"sent": [
{ "to": "anna@example.com", "id": 6, "message_id": "c6fda2e5-4214-4337-b1c4-36f3a27470a4@example.com" }
],
"skipped": []
}
skipped lists addresses that were not written to, with the reason in why:
| Reason | Meaning |
|---|---|
bad_address | Not an email address |
suppressed | The address bounced or complained before; writing again would hurt your domain |
failed | The email could not be queued |
If nobody is left to write to, the answer is 422 with the same skipped list.
What happens next
Follow the fate of each email under Settings → Site keys: queued, sent, not sent or bounced. To be told instead of looking, add a webhook for site emails: it reports email.sent, email.failed and email.bounced with the id from this answer.