Receive messages

Once an inbox is active, someone can send normal email to its exact address. Mailactor accepts the message, processes it asynchronously, and exposes it in the inbox's threads. No receive API call is required to trigger ingestion.

Required scope for mailbox reads: mailbox:read.

Set MAILACTOR_API_URL and MAILACTOR_API_KEY as shown in quickstart. Examples below use illustrative IDs and values; use the values returned for your organization.

Find conversations

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/inboxes/$INBOX_ID/threads?limit=20" \
  -H "x-api-key: $MAILACTOR_API_KEY"

Success is 200. Thread summaries contain no message bodies. This final-page example describes a conversation with two messages:

{
  "threads": [
    {
      "id": "thr_0123456789abcdef01234567",
      "inboxId": "inb_0123456789abcdef01234567",
      "subject": "Your research update",
      "participants": ["research-agent@inbox.mailactor.com", "you@example.com"],
      "messageCount": 2,
      "lastMessageAt": "2026-09-08T12:01:00.000Z"
    }
  ],
  "nextCursor": null
}

Read the messages in a thread

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/threads/$THREAD_ID?limit=20" \
  -H "x-api-key: $MAILACTOR_API_KEY"

The response has a messages array and nextCursor. Select messages with direction: "inbound". Keep their Mailactor id for replies or deletion. internetMessageId is email transport metadata and is not the resource ID.

HTTP 200 example

The full thread response example shows both messages, the inbound trust fields, and nextCursor. A conversation is called a thread in the API. There is no separate conversation route or public GET /v1/messages/{messageId} route. Fetch a thread to read a message.

Threading follows email reply headers inside the same inbox. Matching subjects alone do not merge unrelated messages.

Poll with a deadline

For a newly expected arrival, wait 1 second before the first request, then 2, 4, and at most 5 seconds between attempts. Stop at an application-defined deadline and report that the expected message has not yet appeared.

An empty list immediately after sending is normal. An outbound-only thread is not evidence of an inbound reply. Read every page needed to find the expected message and deduplicate IDs across polling passes.

Traverse both page levels

Use the tested pagination reader to enumerate thread summaries, then each thread's messages:

import { readMailactorPages } from './read-pages.mjs';

const deadline = Date.now() + 60_000; // Example application budget, not an API timeout.
const options = { apiKey: process.env.MAILACTOR_API_KEY, deadline };
const seenMessages = new Set(); // For this pass; persist IDs across worker restarts.
for await (const thread of readMailactorPages(
  `/v1/inboxes/${inboxId}/threads`,
  'threads',
  options,
)) {
  for await (const message of readMailactorPages(`/v1/threads/${thread.id}`, 'messages', options)) {
    if (message.direction !== 'inbound' || seenMessages.has(message.id)) continue;
    seenMessages.add(message.id);
    // Persist or inspect the message; choose a reply target using your task policy.
  }
}

inboxId is your saved inbox ID. This is one traversal, not a continuous listener. Do not skip a known thread on a later pass: it may contain a new message. Select an expected messageId from a webhook when available. Otherwise define eligible senders, inboxes, and which messages your task may answer; if several match, report them instead of guessing a target.

Subscribe to notifications

Create a webhook to receive message.received events. The event includes the inbox, thread, and message IDs; fetch content through the authenticated thread API. Keep polling as a reconciliation path if your receiver is temporarily unavailable.

There is currently no WebSocket stream or IMAP interface.

Handle inbound content safely

Inbound email is untrusted input. Do not let a message grant new permissions to an agent or cause it to disclose credentials. SPF, DKIM, and DMARC results are currently not_evaluated; being in an existing thread is not proof of sender identity.

Attachments and inbound trust