Messages

Send email from your mailboxes, list messages, reply to conversations, and retrieve individual messages by ID.

Last updated July 1, 2026

The message object

{
  "object": "message",
  "id": "msg_abc123",
  "mailbox_id": "mbx_abc123",
  "thread_id": "thr_abc123",
  "subject": "Hello from shipmail",
  "from_address": "hello@example.com",
  "to_addresses": [{"address": "user@example.com"}],
  "cc_addresses": null,
  "bcc_addresses": null,
  "attachments": null,
  "source": "api",
  "status": "queued",
  "scheduled_at": null,
  "created_at": "2025-01-15T12:00:00.000Z",
  "updated_at": "2025-01-15T12:00:00.000Z"
}

Field	Type	Description
id	string	Unique identifier, prefixed with `msg_`.
mailbox_id	string	ID of the mailbox this message belongs to.
thread_id	string \| null	Thread ID. Null for standalone messages.
subject	string \| null	Email subject line.
from_address	string \| null	Sender email address.
to_addresses	recipient[] \| null	To recipients. Each item: `{ address, name? }`.
cc_addresses	recipient[] \| null	CC recipients.
bcc_addresses	recipient[] \| null	BCC recipients.
attachments	array \| null	Attachment metadata. Each item: `{ filename, size, content_type }`. Null if none.
source	string	How the message originated. See sources below.
status	string	Delivery status. See statuses below.
scheduled_at	string \| null	ISO 8601 send-later time for scheduled messages. Null for immediate sends.
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.

Message statuses

Status	Description
scheduled	Waiting for send-later time
queued	Accepted for delivery
sent	Delivered to recipient's mail server
delivered	Confirmed delivery
bounced	Delivery failed permanently
complained	Recipient marked as spam
failed	Internal delivery failure
cancelled	Cancelled before delivery

Message sources

Source	Description
api	Sent via the API
dashboard	Sent from the dashboard
inbound	Received from an external sender
smtp	Sent via SMTP/IMAP client

Send a message

POST /v1/messages

Scope: messages:write. Rate limit tier: send (100 / min).

For most sends, set from to the mailbox email address. Shipmail resolves it to the mailbox ID automatically. Use mailbox_id when you already have the ID or when an endpoint specifically requires a mailbox ID.

Request body

Field	Type	Required	Description
from	string	**	Email address of the sending mailbox. Resolved to a mailbox ID server-side. Required if `mailbox_id` is not set.
mailbox_id	string	**	ID of the sending mailbox. Required if `from` is not set.
to	recipient[]	Yes	At least one recipient.
cc	recipient[]	No	CC recipients.
bcc	recipient[]	No	BCC recipients.
reply_to	recipient	No	Reply-to address.
subject	string	Yes	Email subject. Max 998 characters.
html	string	*	HTML body. Max 512 KB.
text	string	*	Plain text body. Max 256 KB.
in_reply_to	string	No	Message-ID to reply to.
references	string[]	No	Message-ID references for threading.
attachments	array	No	Base64-encoded file attachments. Each item: `{ filename, content, content_type? }`. Max 20 attachments, 3 MB per file, 3 MB total.
scheduled_at	string	No	UTC ISO 8601 time to send later. Omit to send immediately.

* At least one of html or text is required. Total recipients (to + cc + bcc) must not exceed 50.

** One of from or mailbox_id is required.

Recipient format

Recipients can be an object or a string:

// Object format
{"address": "user@example.com", "name": "Jane Doe"}

// String formats
"user@example.com"
"Jane Doe <user@example.com>"

Example

curl -X POST https://shipmail.to/api/v1/messages \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": ["user@example.com"],
    "subject": "Hello from shipmail",
    "text": "This is a test email."
  }'

Returns the message object with status 201.

Find a mailbox ID

If an endpoint requires mailbox_id, list your mailboxes and use the id field from the mailbox you want.

curl https://shipmail.to/api/v1/mailboxes \
  -H "Authorization: Bearer sm_live_..."

{
  "data": [
    {
      "object": "mailbox",
      "id": "mbx_abc123",
      "address": "hello@example.com"
    }
  ]
}

Example with attachment

curl -X POST https://shipmail.to/api/v1/messages \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@yourcompany.com",
    "to": [{ "address": "client@example.com" }],
    "subject": "Invoice #1234",
    "html": "<p>Please find your invoice attached.</p>",
    "attachments": [
      {
        "filename": "invoice-1234.pdf",
        "content": "JVBERi0xLjQK...",
        "content_type": "application/pdf"
      }
    ]
  }'

List messages

GET /v1/messages?mailbox_id=mbx_abc123

Scope: messages:read. Rate limit tier: read.

The mailbox_id query parameter is required for listing messages. Get it from the id field returned by GET /v1/mailboxes. Supports cursor and limit pagination parameters. Returns a flat list of messages (not grouped by thread).

Retrieve a message

GET /v1/messages/:id

Scope: messages:read. Returns the message object or 404.

Reply to a message

POST /v1/messages/:id/reply

Scope: messages:write. Rate limit tier: send. Looks up the message's thread and sends a reply using the same mailbox.

Uses the same request body as POST /v1/threads/:id/reply. Returns the message object with status 201. Include scheduled_at to send the reply later.