Send an email as the mailbox holder

POST/api/v1/mailbox/messages/send
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Sends from this mailbox's own address and files a copy in Sent. Send JSON, or multipart/form-data when you attach files (repeat a field for each value: to, cc, bcc, attachments).

Retrying safely. Send an Idempotency-Key header of the form <app>-<ULID> (for example crm-01JBT8XQ2M9WYC3K4F6R7S8T9V; one per email, saved before the first try). A retry with the same key within 24 hours returns the first answer, with Idempotency-Replayed: true, instead of sending again; while the first is still sending it answers 409 with Retry-After.

Scheduling. With send_at, the message waits in the Scheduled folder and the answer carries send_at; cancel it with DELETE /messages/scheduled/{id}.

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
403 You do not have permission to send from that address (a from this mailbox may not use), or read-only access to a shared mailbox.
409 A send with this Idempotency-Key is still in progress. Wait for Retry-After, then retry with the same key.
422 Add at least one valid recipient, The message has no content, too many or too large attachments, an invalid send_at, an Idempotency-Key that is not <app>-<ULID>, or one reused for a different email.

Parameters

NameInTypeDescription
Idempotency-KeyheaderstringMakes a retry safe. Must look like <app>-<ULID>: your app's name in lowercase, a dash, then a ULID. One per email, sent again on every retry of it. Any other shape is a 422.

Request body

  • toarray<string>

    Recipient addresses. At least one recipient across to, cc and bcc.

  • ccarray<string>

    Copy recipients: everyone sees them.

  • bccarray<string>

    Blind copies: delivered, but no recipient sees them.

  • subjectstring

    The subject line.

  • body_textstring

    The plain-text body. Send this, body_html, or both.

  • body_htmlstring

    The HTML body.

  • in_reply_tostring

    The Message-ID being answered, to thread the reply.

  • in_reply_to_idstring

    That message's id here (INBOX:4821), so it is flagged answered.

  • referencesstring

    The References header of the message being answered.

  • send_atstring

    ISO 8601 (UTC). Schedule instead of sending now.

  • fromstring

    A shared mailbox to send as; must be one this mailbox may send from (see capabilities).

  • mentionsarray<string>

    Addresses @-mentioned in the body.

  • forward_attachments_fromstring

    Forwarding: the message id whose attachments to include.

  • attachment_indexesarray<integer>

    Forwarding: which of its attachments (from its attachments).

  • attachmentsarray<string>

    Files, multipart only: up to 20, 25 MB in total.

Request

POST/api/v1/mailbox/messages/send
curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/messages/send' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      "tunde@example.com"
    ],
    "subject": "The Q3 figures",
    "body_text": "Hi Tunde,\n\nThe figures are below.\n\nAda"
  }'

Response

Sent, or scheduled.

  • dataobject
    • idstring or null

      The copy in Sent (Sent:413), or in Scheduled. Null if it was sent but could not be filed.

    • message_idstring

      The Message-ID the email went out with.

    • answered_idstring or null

      The message flagged answered, for a reply.

    • folderstring

      Scheduled only.

    • send_atstring

      Scheduled only.

200application/json
{
  "type": "success",
  "msg": "Message sent",
  "data": {
    "id": "Sent:413",
    "message_id": "<9f86d081.idem@yourdomain.com>",
    "answered_id": null
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403`You do not have permission to send from that address` (a `from` this mailbox may not use), or read-only access to a shared mailbox.
409A send with this `Idempotency-Key` is still in progress. Wait for `Retry-After`, then retry with the same key.
422`Add at least one valid recipient`, `The message has no content`, too many or too large attachments, an invalid `send_at`, an `Idempotency-Key` that is not `<app>-<ULID>`, or one reused for a different email.

Every status, with what causes it and what to do, is on the error reference.