Skip to content

ResourcesThreads

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.

ValueMeaning
needs_replyThe last message came in and wants an answer.
waiting_on_themYou wrote last and track the reply. Nothing has come back.
doneMarked done.
follow_up_dueA follow-up date passed.
delivery_failedYour last message bounced or failed.
no_actionNothing to do.

List threads

GET/v1/threads?mailbox_id=f47ac10b-58cc-4372-a567-0e02b2c3d479scope threads:readtier read

mailbox_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

ParameterDescription
mailbox_idThe mailbox. Required unless batch_id is given.
attention_stateOne or more states, comma-separated (attention_state=a,b).
afterISO 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.
beforeISO 8601 date-time with an offset. Only threads whose same time is before it.
batch_idOnly 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

GET/v1/threads/:id?mailbox_id=f47ac10b-58cc-4372-a567-0e02b2c3d479

Scope: 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

POST/v1/threads/:id/reply

Scope: 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

FieldTypeRequiredDescription
mailbox_idstringYesMailbox that owns the thread.
htmlstringOne of html, textHTML body. Max 512 KB.
textstringOne of html, textPlain text body. Max 256 KB.
torecipient[]YesTo recipients. At least one required.
ccrecipient[]NoCC recipients.
bccrecipient[]NoBCC recipients. To, CC and BCC together are at most 50.
track_replybooleanNotrue 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_signaturebooleanNotrue 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.