Threads API
A thread is one conversation: the message and every reply to it. You can list a mailbox's threads, read the messages in one, and reply to it.
Last updated
Conversation IDs
conversation_id is Shipmail's own ID for a conversation, like thd_abc123. Store this one. It stays the same when threads merge or when the mail server re-threads its own IDs.
thread_id and the thread object's id are legacy IDs. They are deprecated and they change. A thread object's id is the conversation's legacy key. For a message sent through SMTP relay, it starts as a placeholder and changes once the mail server files the copy. A message's thread_id is the ID the mail server last reported, and it changes when the server re-threads. So GET /v1/messages/:id can show a different value than the thread list. Every endpoint with a thread ID in its path accepts a conversation_id, so pass that.
The thread object
{
"object": "thread",
"id": "thr_abc123",
"conversation_id": "thd_abc123",
"mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subject": "Re: Pricing question",
"message_count": 3,
"latest_message": {
"object": "message",
"id": "msg_latest",
"mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"thread_id": "thr_abc123",
"conversation_id": "thd_abc123",
"subject": "Re: Pricing question",
"from_address": "customer@example.com",
"to_addresses": [{"address": "hello@example.com"}],
"cc_addresses": null,
"bcc_addresses": null,
"attachments": null,
"source": "inbound",
"status": "delivered",
"created_at": "2026-05-13T10:00:00.000Z",
"updated_at": "2026-05-13T10:00:00.000Z"
},
"attention_state": "needs_reply",
"attention_since": "2026-05-13T10:00:00.000Z",
"created_at": "2026-05-12T10:00:00.000Z",
"updated_at": "2026-05-13T10:00:00.000Z"
}attention_state says where the conversation stands, as the inbox shows it: a passed follow-up date reads follow_up_due and a muted conversation no_action. attention_since says since when: for waiting_on_them, when your tracked message went out; for follow_up_due, the follow-up date. It is null for no_action, done and when not known. The mailbox attention queue, GET /v1/mailboxes/:id/inbox/threads, reports the same values and takes the same filters.
| Value | Meaning |
|---|---|
| needs_reply | The last message came in and wants an answer. |
| waiting_on_them | You wrote last and track the reply. Nothing has come back. |
| done | Marked done. |
| follow_up_due | A follow-up date passed. |
| delivery_failed | Your last message bounced or failed. |
| no_action | Nothing to do. |
List threads
/v1/threads?mailbox_id=f47ac10b-58cc-4372-a567-0e02b2c3d479scope threads:readtier readmailbox_id is required unless you pass batch_id. Without it, the list spans every mailbox the API key may read. Page through results with cursor and limit.
Filters
| Parameter | Description |
|---|---|
| mailbox_id | The mailbox. Required unless batch_id is given. |
| attention_state | One or more states, comma-separated (attention_state=a,b). |
| after | ISO 8601 date-time with an offset, like 2026-11-05T00:00:00Z. Only threads whose attention_since, or last message time when it is null, is at or after it. |
| before | ISO 8601 date-time with an offset. Only threads whose same time is before it. |
| batch_id | Only conversations that contain a message of this POST /v1/messages/batch request, in any mailbox the key may read. |
Returns a page of thread summaries. The thread with the newest message comes first. A bad filter value, or an after that is not earlier than before, is a 422.
To list who in a batch has not replied since a date, combine the filters:
curl "https://shipmail.to/api/v1/threads?batch_id=msgb_abc123&attention_state=waiting_on_them&before=2026-11-05T00:00:00Z" \
-H "Authorization: Bearer $SHIPMAIL_API_KEY"See Outreach with review for the whole loop.
Retrieve thread messages
/v1/threads/:id?mailbox_id=f47ac10b-58cc-4372-a567-0e02b2c3d479Scope: threads:read. Returns a paginated list of messages in the thread. mailbox_id is required, because a thread ID is only unique inside one mailbox. Page with cursor and limit.
Reply to a thread
/v1/threads/:id/replyScope: messages:send. Rate limit tier: send. Sends the reply from the mailbox you name in the required mailbox_id body field.
With a key that holds email to outside addresses for review, a reply to anyone outside your domains is saved as a reply draft of this conversation and the endpoint answers 202 with a held_message instead of sending.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| mailbox_id | string | Yes | Mailbox that owns the thread. |
| html | string | One of html, text | HTML body. Max 512 KB. |
| text | string | One of html, text | Plain text body. Max 256 KB. |
| to | recipient[] | Yes | To recipients. At least one required. |
| cc | recipient[] | No | CC recipients. |
| bcc | recipient[] | No | BCC recipients. To, CC and BCC together are at most 50. |
| track_reply | boolean | No | true adds the conversation to Waiting; false untracks it. Omit to keep the thread's current tracking, so a reply on a tracked conversation stays tracked. |
| add_signature | boolean | No | true ends the reply with the mailbox's shared signature, in each part you send. Nothing is added when the mailbox has no signature. |
You can send to at most 50 recipients, to and cc combined.
Returns the message object with status 201.