Messages

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

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",
  "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.
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.

Message statuses

Status	Description
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

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).

Request body

Field	Type	Required	Description
mailbox_id	string	**	ID of the sending mailbox. Required if `from` is not set.
from	string	**	Email address of the sending mailbox. Resolved to a mailbox ID server-side. Required if `mailbox_id` 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.

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

** One of mailbox_id or from 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.

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. 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.