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.

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.

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.

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' mailboxes. Inkbox combines a mode — whitelist or blacklist — with a list of contact rules to decide whether inbound mail is delivered.

Every mailbox has a 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, paused, or deleted) — 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 to manage the mailbox resource itself — creating one outside of the identity flow, updating its webhook, searching across all messages, or deleting it. For that, use inkbox.mailboxes.