Sending

Send new email or reply in a thread from any of your active inboxes. Replies thread correctly in the recipient's mail app, and their answers come back to the same thread.

Send an email #

POST /v1/inboxes/{inbox_id}/messages

Sends an email that starts a new thread, and returns the sent message.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.

Headers

Idempotency-Key string: Recommended. Any unique value, up to 255 characters. Repeating a request with the same key within 24 hours returns the first response instead of sending again.

Body

to string[] required: Recipients, up to 50. Jane Doe <jane@example.com> works too.
cc string[]: Up to 50.
bcc string[]: Up to 50. Hidden from other recipients.
subject string required: One line, up to 998 characters.
text string: Plain-text body. Send text, html or both.
html string: HTML body.
attachments array: Files to attach, each { filename, content_type, content } with content in base64. Up to 10 files and 5 MB in total.

If any recipient is on your block list, nothing is sent and you get 422 with the blocked addresses.
Each email counts toward your monthly sending limit. A send that fails is not counted.

curl

curl -X POST "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/messages" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "to": ["jane@example.com"],
    "subject": "Your order has shipped",
    "text": "Hi Jane, your order is on its way.",
    "html": "<p>Hi Jane, your order is <b>on its way</b>.</p>"
  }'

Response

{
  "object": "message",
  "id": "msg_mvdliiuwzfsa7ngv",
  "thread_id": "thr_mvdlijmoxjmnbx5g",
  "inbox_id": "inb_mvdlh9c06724trm1",
  "direction": "out",
  "from": { "address": "support-agent@mailbox.maila.ai", "name": "Support Agent" },
  "to": ["jane@example.com"],
  "cc": [],
  "subject": "Your order has shipped",
  "text": "Hi Jane, your order is on its way.",
  "status": "sent",
  "message_id": "<010f01a14f82…@us-east-2.amazonses.com>",
  "received_at": 1792335390,
  "attachments": []
}

Reply to a thread #

POST /v1/inboxes/{inbox_id}/threads/{thread_id}/reply

Replies to the latest message in the thread. Recipients and the subject (Re: …) are filled in for you.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required: The thread, for example thr_mvdlijmoxjmnbx5g.

Headers

Idempotency-Key string: Recommended. Any unique value, up to 255 characters. Repeating a request with the same key within 24 hours returns the first response instead of sending again.

Body

text string: Plain-text body. Send text, html or both.
html string: HTML body.
reply_all boolean: Also reply to everyone else on the message. Default false.
attachments array: Files to attach, each { filename, content_type, content } with content in base64. Up to 10 files and 5 MB in total.

curl

curl -X POST "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g/reply" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-invoice-question" \
  -d '{ "text": "Thanks Jane, we have refunded the duplicate charge." }'