Messages API
Send email from your mailboxes, list and fetch messages, reply to conversations, and answer calendar invitations.
Last updated
The message object
{
"object": "message",
"id": "msg_abc123",
"mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"thread_id": "thr_abc123",
"conversation_id": "thd_abc123",
"source_rfc_message_id": "<crm-123@example.com>",
"delivered_rfc_message_id": null,
"client_reference": "crm-123",
"batch_id": null,
"metadata": {"campaign": "onboarding"},
"headers": [{"name": "X-CRM-ID", "value": "crm-123"}],
"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",
"mode": "live",
"status": "queued",
"rule_disposition": null,
"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 | Deprecated. The thread ID the mail server last reported for this message. It still works in thread paths, but it can change when the server re-threads and can differ from the ID in the thread list. Use conversation_id. Null for standalone messages. |
| conversation_id | string | null | Shipmail's own conversation identifier, prefixed with thd_. Store this one: it survives merges and re-threading. Null until Shipmail adds the message to a conversation. A message you relayed over SMTP stays null until Shipmail finds its copy in the mailbox, which takes at most 24 hours, so it ends up in the same conversation as the replies to it. |
| source_rfc_message_id | string | null | The Message-ID you supplied, or the one Shipmail saw before relaying. |
| delivered_rfc_message_id | string | null | The exact Message-ID the provider assigned, once Shipmail sees it in a recipient's reply. Null until then. Shipmail never rebuilds it from the SES ID. |
| client_reference | string | null | Your own reference for this message, unique within your organization. |
| batch_id | string | null | The POST /v1/messages/batch request the message came from, also when a person sent it from a held draft of that batch. |
| metadata | array | Up to 20 scalar keys and 8 KB of JSON. |
| headers | object | The safe outbound headers kept with the message, normalized. |
| 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. |
| mode | string | Data plane that owns the message: live or test. |
| status | string | Delivery status. See statuses below. |
| rule_disposition | object | null | For an inbound tracked message, the inbox rules that ran when it was delivered: { matched_rule_ids: string[], stop_rule_id: string | null }. Null for outbound messages, older messages, or when no rule evaluation is available. Inbox message objects that come from JMAP do not have this field. |
| scheduled_at | string | null | ISO 8601 time a scheduled message will send. 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 |
| suppressed | Blocked before it reached the provider because a recipient is suppressed |
| cancelled | Cancelled before delivery |
Message sources
| Source | Description |
|---|---|
| api | Sent through the API |
| dashboard | Sent from the dashboard |
| newsletter | Sent by a newsletter campaign |
| inbound | Received from an external sender |
| smtp | Sent from an SMTP or IMAP client |
| agent | Sent from a versioned agent reply draft |
Send a message
/v1/messagesScope: messages:send. Rate limit tier: send (100 / min).
For most sends, set from to the mailbox address and Shipmail finds the mailbox ID. To set the sender name for one send, use the RFC 5322 form Acme Support <hello@example.com>. A bare address uses the display name saved on the mailbox. Use mailbox_id when you already have the ID, or when an endpoint asks for one.
To send from a transactional sender, set from to its bare address. Shipmail adds the sender name, and the sender's Reply-To when reply_to is left out. The API refuses scheduled_at, track_reply: true, staged_attachment_ids or a different display name with a 422 whose details[].code starts with transactional_sender_. A sender that is off, or one the API key cannot send from, returns 403 transactional_sender_unavailable. A transactional send that hits a limit returns 429 with application_daily_limit (the transactional daily limit: the safety limit or its plan floor, or an approved limit), application_unique_recipients (different recipients per hour), application_storage_full (transactional email storage) or sending_capacity (Shipmail's sending capacity for transactional email; retry in a few minutes). During a free trial, a transactional send past the trial's 100 recipients a day returns 429 with daily_limit, like any other send. The codes daily_limit_ramp_up and hourly_limit_ramp_up are no longer returned. When the organization is metered in emails, a send past its limit returns 403 quota_exceeded with transactional_monthly_limit, transactional_payment_failed or transactional_budget_reached. If the sender has Refuse temporary email addresses on, a send to a throwaway email domain returns 422 recipient_disposable.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| from | string | One of from, mailbox_id | Email address of the sending mailbox, bare or as Name <address>. Shipmail resolves it to a mailbox ID. A name, if given, replaces the mailbox display name for this send. Required if mailbox_id is not set. |
| mailbox_id | string | One of from, mailbox_id | 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, unless you send a template | Email subject. Max 998 characters. |
| html | string | One of html, text, unless you send a template | HTML body. Max 512 KB. |
| text | string | One of html, text, unless you send a template | Plain text body. Max 256 KB. |
| template | object | No | Send a stored template instead of subject, html and text: { id, version?, variables? }. See Send with a template below. |
| in_reply_to | string | No | Message-ID this message replies to, sent as the In-Reply-To header. The message joins the conversation of the stored message with this Message-ID when it is found in exactly one conversation of the mailbox. Otherwise it starts its own. |
| references | string[] | No | Message-IDs sent as the References header, for threading in the recipient's mail client. They never decide or merge conversations. |
| attachments | array | No | Deprecated base64-encoded file attachments. Each item: { filename, content, content_type? }. Max 20 attachments. The whole email can be up to 10 MB, attachments and encoding included; a larger one returns 422. An HTML, SVG or script content type returns 422, and so does a program or script file extension such as .exe. |
| staged_attachment_ids | string[] | No | IDs from the raw staged-attachment endpoint. Max 20 files, 25 MB per file. Each ID only works with the API key, organization and sending mailbox that staged it. |
| scheduled_at | string | No | UTC ISO 8601 time to send later. Leave it out to send now. |
| track_reply | boolean | No | true adds the conversation to Waiting and false removes it. Leave it out to keep the current tracking, so a reply on a tracked conversation stays tracked. |
| add_signature | boolean | No | true adds the mailbox's shared signature after your text: at the end of text and before </body> in html. Its name field takes the name in from, else the mailbox display name. Nothing is added when the mailbox has no signature. Transactional senders refuse it. |
| client_reference | string | No | Unique within your organization and mode. Sending again from the same mailbox with a reference already in use sends nothing and returns the original message with 201, without comparing bodies. The same reference from another mailbox returns 409. Use it to look the message up later. |
| metadata | object | No | Up to 20 string, number, boolean, or null values; 8 KB total. |
| source_rfc_message_id | string | No | RFC Message-ID in <local@domain>form. The domain must match the sender. |
| headers | array | No | Up to 20 safe headers: RFC 8058 unsubscribe headers or non-reserved X-* headers. Shipmail rejects control characters and Shipmail or SES internal headers. |
A message can have at most 50 recipients across to, cc and bcc.
Recipient format
Write each recipient as 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.",
"client_reference": "crm-123",
"metadata": {"campaign": "onboarding"},
"source_rfc_message_id": "<crm-123@example.com>",
"headers": [{"name": "X-CRM-ID", "value": "crm-123"}]
}'Returns the message object with status 201.
When the key holds email to outside addresses for reviewand a recipient is outside your organization's domains, nothing is sent. The email is saved to the mailbox's Drafts and the response is202 with a held_messagenaming the draft and the outside recipients. A person sends it from Shipmail. client_reference, metadata and track_reply are kept with the draft and applied to the message the person sends. A repeated client_reference answers 202 with the first hold, or 201 with the sent message once a person sent the draft.
Send with a template
Pass template to send a stored template. Shipmail renders its subject and body with your variables, then sends it like any other message, so every other field works unchanged. The scope is still messages:send.
{
"from": "hello@example.com",
"to": ["ada@example.com"],
"template": {
"id": "tpl_123",
"variables": { "name": "Ada", "seats": 3 }
}
}| Field | Type | Description |
|---|---|---|
| template.id | string | Template ID, such as tpl_123. Required. |
| template.version | integer | Send this published version. Omit it to send the current published version. |
| template.variables | object | Value per variable key: a string, number or boolean. Keys with a fallback are optional. |
A template that does not exist or belongs to another organization, or a version that does not exist, returns 404. These return 422 with a details[].code:
| Code | Meaning |
|---|---|
| template_conflict | The request also sent subject, html or text. |
| template_not_published | The template has no published version and the request did not pin one. |
| missing_variable | A variable without a fallback was left out. The field is template.variables.<key>. |
| unknown_variable | The template does not use this variable. |
Find a mailbox ID
If an endpoint needs mailbox_id, list your mailboxes and copy the id of the one you want.
curl https://shipmail.to/api/v1/mailboxes \
-H "Authorization: Bearer sm_live_..."
{
"data": [
{
"object": "mailbox",
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"address": "hello@example.com"
}
]
}Stage and send an attachment
Upload the raw bytes first. That skips the base64 overhead and allows files up to 25 MB. The staged ID expires after 24 hours and only works with the same key and mailbox.
curl -X POST "https://shipmail.to/api/v1/mailboxes/mbx_123/staged-attachments?filename=invoice-1234.pdf" \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/pdf" \
--data-binary @invoice-1234.pdf
# Response contains: { "id": "sat_..." }
curl -X POST https://shipmail.to/api/v1/messages \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{
"mailbox_id": "mbx_123",
"to": [{ "address": "client@example.com" }],
"subject": "Invoice #1234",
"html": "<p>Please find your invoice attached.</p>",
"staged_attachment_ids": ["sat_..."]
}'Send your own calendar invitation
To send an invitation you built yourself, attach its .ics file with type text/calendar, staged or inline. When the file's METHOD is REQUEST and its ORGANIZER is the sending mailbox, Shipmail puts the event on that mailbox's calendar once the message is on its way, with the attendees from the file, and records their answers on it as they come in. Sending a new version with the same UID and a higher SEQUENCE updates the event; METHOD:CANCEL removes it when it cancels the whole meeting (STATUS:CANCELLED, or every guest). A cancellation sent to some guests only leaves the event in place. Shipmail sends no invitation email of its own: your message is the invitation.
This needs an API key with calendar:write as well as messages:send. Shipmail leaves the calendar alone when the organizer is someone else, for a scheduled or test-mode send, for a change to one occurrence of a series (RECURRENCE-ID), for a version older than the stored event, for a send Shipmail answers from a message it already sent, and for an event with that UID that another organizer owns. A calendar error never fails the send. To have Shipmail write and send the invitation for you, use POST /v1/calendar/events with attendees instead.
Prepare a browser-hosted upload
When a browser component must not see your Shipmail API key, get it a single-use upload URL that lasts five minutes. Send the sanitized filename, normalized MIME type, exact byte size and lowercase SHA-256 digest to POST /v1/mailboxes/:id/staged-attachment-upload-tokens. Then upload the exact raw bytes to the returned URL, with no credentials and no redirects. The URL rejects any metadata or digest mismatch and stops working after one successful upload.
curl -X POST https://shipmail.to/api/v1/mailboxes/mbx_123/staged-attachment-upload-tokens \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{
"filename": "invoice-1234.pdf",
"content_type": "application/pdf",
"size": 184320,
"sha256": "<64 lowercase hexadecimal characters>"
}'
# POST the exact raw bytes to the upload_url returned above.
# No Authorization or Idempotency-Key header is used.Manage scheduled messages
GET /v1/scheduled-messages
GET /v1/scheduled-messages/:message_id
PATCH /v1/scheduled-messages/:message_id
DELETE /v1/scheduled-messages/:message_idList and retrieve use messages:read. Update and cancel use messages:send. Set include_held=true on the list call to also see undo-send holds. An update replaces recipients, content, staged attachments and delivery time, as long as Shipmail has not picked the message up to send. Leave out both html and text to move a send in time and keep the stored body. That is how you reschedule a rich HTML send without sending its content again. Send either field and the whole body is replaced. Once sending has started, you cannot cancel it.
Each scheduled message has a status. scheduled means it is waiting for its send time. settling means a send attempt may already have gone out and Shipmail is checking whether it did. Until Shipmail knows, update and cancel return 409. The message then leaves the list as sent, or goes back to scheduled to be sent again. Treat any other value as not editable.
Send a batch
/v1/messages/batchscope messages:sendtier sendSends 1 to 50 messages in one request. Each item in messages is exactly a POST /v1/messages body and goes through the same checks. Test keys are allowed.
{
"messages": [
{
"from": "sales@example.com",
"to": ["ada@client.example"],
"subject": "Quick question",
"text": "Hi Ada, ...",
"client_reference": "lead-42",
"metadata": { "campaign": "q4" },
"track_reply": true
}
]
}The response is 200 with a batch_id and one result per item, in request order: the message object (sent or scheduled), a held_message (held for review, nothing sent), or an error. A refused item does not stop the others.
{
"object": "message_batch",
"batch_id": "msgb_abc123",
"data": [
{ "object": "message", "id": "msg_1", "batch_id": "msgb_abc123", "status": "queued" },
{
"object": "held_message",
"status": "held_for_review",
"draft_id": "Mabc123",
"mailbox_id": "0b6f8d2e-3c41-4a8e-9f1d-6a2b5c7e9d10",
"external_recipients": ["bob@client.example"],
"client_reference": "lead-43",
"batch_id": "msgb_abc123"
},
{
"object": "error",
"index": 2,
"status": 422,
"error": { "type": "validation_error", "message": "Validation failed.", "request_id": "req_123" }
}
]
}An error item carries the status and the error the item alone would have had from POST /v1/messages. The request itself fails with 400 for invalid JSON, 413 over 24 MB, 422 for no items, more than 50 or an unknown field, and 429 when the batch does not fit your per-minute send limit. Every message after the first counts, so a batch of 50 counts as 50 sends.
With an Idempotency-Key, a retry returns the stored response. A batch retried with the same key keeps its batch_id, and each item gets its own key from the batch key and its position, so no item is sent twice and a held item answers with the same hold. Every message records the batch_id, and so does the message a person later sends from a held draft. Find them again with GET /v1/messages?batch_id= and GET /v1/threads?batch_id=. A draft still waiting for review is not listed there, so keep the batch response.
List messages
GET /v1/messages?mailbox_id=f47ac10b-58cc-4372-a567-0e02b2c3d479
GET /v1/messages?client_reference=crm-123
GET /v1/messages?batch_id=msgb_abc123Scope: messages:read. Rate limit tier: read.
Pass at least one of mailbox_id, client_reference or batch_id. A client reference match is exact, limited to your organization, and follows the API key's mailbox and domain restrictions. Page with cursor and limit. You get a flat list of messages, not grouped by thread.
Sync message analytics
GET /v1/messages/analytics?updated_after=2026-07-01T00:00:00.000Z&limit=100
{
"data": [{
"object": "message_analytics",
"id": "msg_abc123",
"mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"thread_id": "thr_abc123",
"conversation_id": "thd_abc123",
"client_reference": "crm-123",
"direction": "outbound",
"contact_addresses": ["user@example.com"],
"recipient_count": 2,
"attachment_count": 1,
"source": "api",
"mode": "live",
"status": "delivered",
"scheduled_at": null,
"created_at": "2026-07-28T09:00:00.000Z",
"updated_at": "2026-07-28T09:00:05.000Z"
}],
"pagination": {
"next_cursor": null,
"has_more": false,
"limit": 100,
"snapshot_at": "2026-07-29T12:00:00.000Z"
}
}Scope: messages:read. This endpoint lists every message the API key can see across the organization, in stable ascending (updated_at, id) order. updated_after is inclusive. updated_before is exclusive and cannot be later than the server's current time.
On the first page, leave out updated_before. Shipmail then fixes a snapshot a few seconds behind server time, and behind the start of any database transaction still open, so no write still committing can land behind it. An updated_after later than that snapshot returns an empty page with the same snapshot_at. Follow next_cursor until has_more is false, then save snapshot_at as the next sync's updated_after. The signed cursor keeps the organization, API key, mailbox access scope, mode, window, and last (updated_at, id) position.
The analytics object leaves out subjects, BCC addresses, headers, free-form metadata, attachment filenames, mailbox auto-reply content, and message bodies. contact_addresses still contains personal data: the inbound sender or outbound To/Cc addresses, as the mail server received them, so a strict email format check can reject some of them. BCC recipients only contribute to recipient_count. client_reference is caller-defined text and may also contain personal or customer data.
Hard-deleted messages drop out of the results and leave no tombstone. If your connector mirrors deletions, run a full refresh from time to time.
Retrieve a message
/v1/messages/:idScope: messages:read. Returns the message object or 404.
Reply to a message
/v1/messages/:id/replyScope: messages:send. Rate limit tier: send. The path ID must be the stored Shipmail msg_ ID that the messages API or a webhook returned. Shipmail finds that message's thread and replies from the same mailbox.
Takes the same request body as POST /v1/threads/:id/reply and returns the message object with status 201. Add scheduled_at to send the reply later. Set track_reply to true to add the conversation to Waiting, or leave it out to keep the current tracking. Set add_signature to true to end the reply with the mailbox's shared signature.
With a key that holds email to outside addresses for review, a reply to anyone outside your domains is saved as a draft in the conversation instead, and the endpoint answers 202 with aheld_message.
You cannot reply to transactional email. The endpoint returns 422 with transactional_reply_unsupported. Send a new message instead.
The mailbox inbox endpoints return JMAP IDs, scoped to one mailbox. To reply to one of those, use POST /v1/mailboxes/:mailbox_id/inbox/messages/:message_id/reply.
Answer a calendar invitation
/v1/messages/:id/invitationScope: calendar:write. Rate limit tier: write. Accepts, tentatively accepts or declines the invitation a received message carries. The path ID is the message's msg_ ID, such as the tracked_message_id of a message.received webhook, whose invitation field tells you which messages carry one. The body is { "response": "accepted" }, with accepted, tentative or declined.
curl -X POST https://shipmail.to/api/v1/messages/msg_123/invitation \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{ "response": "accepted" }'
{
"object": "invitation_response",
"message_id": "msg_123",
"response": "accepted",
"replied": true,
"calendar_event_id": "evt_..."
}Shipmail stores the answer on the mailbox calendar, including a decline, and returns the event as calendar_event_id. It emails the answer to the organizer only when the organizer sent the message, so a forwarded invitation never makes your mailbox write to a stranger. replied says whether that email went out.
The endpoint returns 404 when the message does not exist, and 422 when it has no invitation, is another guest's reply, the meeting was cancelled, a newer version is already on the calendar, or it is transactional email. An API key that may only write to some recipients gets 403 when the organizer is not one of them.