Each agent identity can have one inbox. Email operations scope to it automatically, your agent always sends from the same address, receives replies in the same place, and builds up a searchable message history over time. This makes it possible for agents to hold real, ongoing email conversations with people, not just fire off one-off messages.

The simplest case is a plain-text or HTML email to one or more recipients.

Branding footer

Outgoing emails include a short "Sent via Inkbox" footer by default. Organizations on a paid plan can remove it: use the "Email footer" setting on the Inkbox Console Email page, or set remove_branding_footer to true with PUT /api/v1/billing/settings using an admin API key. On the Free plan the footer always applies, and the request returns 403.

Threaded replies

When your agent needs to continue a conversation, pass in_reply_to_message_id with the RFC 5322 message_id of the message you're replying to. Inkbox links the reply to the existing thread, so the recipient sees one continuous conversation rather than a new email.

Attachments

Attachments are passed as base64-encoded content with a filename and MIME type.

Forwarding

Forward an email you've already received (or sent) to someone else. Forwards start a brand-new thread — the recipient sees a fresh conversation, not a continuation of the original. Pass mode="wrapped" when you need to preserve fidelity (inline images, calendar invites, complex multipart); the default "inline" renders a Gmail-style preamble with the original body below.

Forwards count against the same send rate limits as send_email.

Reply to everyone

Reply to every visible participant on a message in one call. Inkbox resolves the recipients from the original server-side — the original sender (or its Reply-To) goes in To, the remaining To/Cc recipients go in Cc, and your own mailbox and any BCC recipients are dropped. The reply stays in the original thread, and the subject defaults to "Re: " + original.subject.

Reply-all counts against the same send rate limits as send_email.

Tracking opens

Pass track_opens when sending or forwarding to embed an invisible pixel in the HTML body. The message then reports first_opened_at (the reliable signal) and open_count (an approximate figure — image proxies inflate it and rapid repeat opens deflate it). It needs an HTML body, and the pixel can nudge spam scores.

iter_emails() pages through the identity's entire inbox. Use it in an agent processing loop to handle new messages as they arrive.

For event-driven agents that only need to act on new messages, use iter_unread_emails() and mark messages as read once processed so you don't handle them twice.

Fetching a specific message by id with an API key marks it read automatically (inbound messages only), so if you fetch each message individually you don't need a separate mark-read step. Processing straight from the list without fetching each one still needs the explicit mark-read call, since list and thread reads never change read state.

Every email exchange is grouped into a thread. Use get_thread() to load all messages in a thread at once — for example, to give your LLM full conversation context before generating a reply.

Keep unwanted senders out of your agents' inboxes. Inkbox combines a mode — whitelist or blacklist — with a list of contact rules to decide whether inbound mail is delivered. Both live on the agent identity, addressed by agent_handle.

Each identity has a mail_filter_mode field with two values:

• blacklist (default). Everything is delivered unless a block rule matches the sender.
• whitelist. Nothing is delivered unless an allow rule matches the sender.

Mail rules match on exact_email (e.g. jane@acme.example) or domain (e.g. acme.example). Rules carry an action (allow or block) and a status (active or paused) — paused rules reserve the target slot without taking effect, which is useful for staging policy changes.

Most agents start in blacklist mode: accept everyone, add explicit blocks for spam domains or individual bad actors. Switch to whitelist when you want the opposite — locked down by default, with a known allowlist.

Most mail operations go through the identity, but sometimes you need the mailbox resource itself — for example, to search across all its messages. For that, use inkbox.mailboxes. Mailboxes are created and destroyed through the identity surface, and filter mode now lives on the identity as mail_filter_mode; this resource is for reading and search. Webhook delivery is configured separately — see the Webhooks guide.

Every inbox also speaks IMAP and SMTP, so you can open your agent's mail in a standard desktop or mobile mail app — handy for watching what an agent is doing, or for replying by hand. You sign in with the inbox address and an identity-scoped API key; reads, archives, deletes, and sent mail stay in sync with the API in both directions.

See Use a mail app (IMAP/SMTP) for the connection settings and setup.