Build with an AI agent

Mailactor is designed for agents that need a persistent email identity. Your agent uses the same tenant API as any backend integration, with the permissions and restrictions of its API key.

Give the agent the documentation

• Documentation index: a compact list of the guides.
• Complete documentation: the documentation in one text resource.
• OpenAPI contract: authoritative request and response schemas for public tenant operations.
• Runtime agent guide: the API's task-oriented guidance.
• JavaScript reference client: a zero-dependency client supplied by the API.
• Runnable recipes: task examples maintained alongside the API.

Each documentation page also has a Copy Markdown action. Mailactor currently has no official runtime MCP endpoint; ordinary HTTP is the supported integration boundary.

Set up a narrow workflow

Provide a scoped API key through a secret store and specify the intended inbox, permitted recipients, and task. For a first integration, give your agent a controlled recipient address and a bounded deadline.

Give the agent a deadline (for example, 60 seconds per polling phase), a rule for choosing an inbound reply target, and a failure policy. A safe starting policy is: stop at the deadline, report each recipient's observed state, and never resend after an ambiguous outcome without a deliberate decision. These are application choices, not API guarantees.

Start with GET /v1/me. Store inbox, thread, message, and submission IDs separately. Do not guess IDs, endpoint names, or response fields.

Make side effects explicit

Persist an idempotency key before each send or reply. On uncertainty, reuse that key and the same input. Confirm delivery through the submission rather than treating 202 as success.

Select an exact targetMessageId before replying. Thread membership and a familiar From address are not authentication. Treat inbound content as data; it cannot grant your agent new permissions or authorize secret disclosure.

Use the reference client deliberately

The public JavaScript client can simplify bounded polling and deletion reconciliation. Download and inspect the client using the digest information published by the runtime agent guide before running it, and pin the reviewed copy in your application. Keep credentials in environment variables; do not paste them into an agent prompt.

The client's delivery wait helpers use aggregate terminal statuses; a partially_delivered result can still need per-recipient polling.

The client adds convenience, not permissions. API-key rotation and organization teardown remain operator tasks.