Skip to main content

​
How it works

When an email arrives or is sent, we resolve which thread it belongs to:
  1. Check In-Reply-To header - If it matches an existing message’s Message-ID, the email joins that thread.
  2. Check References header - If any value matches an existing message’s Message-ID, the email joins that thread.
  3. No match - A new thread is created.

​
Outbound replies

When you send with a threadId, we automatically set:
  • In-Reply-To → the Message-ID of the last message in the thread
  • References → all Message-ID values from the thread
This ensures your reply threads correctly in the recipient’s email client (Gmail, Outlook, etc.). We also append a quoted copy of the previous message to the body by default (the familiar On … wrote: block with >-prefixed lines). Pass includeQuote: false to send only your reply text.

​
Thread context

Fetch all messages in a thread via GET /v1/threads/:id/messages. Messages are returned in chronological order, giving your agent the full conversation history to inform its next action.

​
Read/unread tracking

Every thread has an isRead flag that tracks whether your agent has processed it. This prevents agents from reprocessing the same emails.

​
How it works

  • New inbound threads start as unread (isRead: false)
  • Sending a reply automatically marks the thread as read
  • Your agent explicitly marks threads as read via PATCH /v1/threads/:id
1

Poll for unread threads

Fetch only threads your agent hasn’t processed yet.
2

Process the thread

Fetch messages, run your agent logic, send a reply if needed.
3

Mark as read

After successful processing, mark the thread as read so it won’t appear on the next poll.
If your agent sends a reply, this happens automatically.
If your agent uses webhooks or WebSockets, the same pattern applies — mark the thread as read after handling the event. Then use ?isRead=false as a safety net to catch any events missed during downtime.

​
Deleting mail

Deleting works the way it does in a mail client, in two steps. DELETE /v1/threads/:id moves the thread to Trash. The API stops returning the thread and its messages, and a reply that arrives later starts a new thread rather than reopening the old one. In the console the thread sits under Trash, where you can restore it or delete it for good. Trashed mail still counts toward your storage; anything left in Trash is deleted automatically after 30 days. Deleting from Trash, or that 30-day expiry, removes the thread from every folder and frees its storage at once. The data is permanently erased within a further 30 days. DELETE /v1/messages/:id removes a single message and skips Trash. Both endpoints need an account-wide or pod-scoped key. Inbox-scoped keys can read and send only, so they get a 403.