Email

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. You can also import existing mail history from MBOX, EML, or ZIP archives.

Importing email history

Use mailboxes.imports to create an import job, upload the archive directly, start processing, and wait for completion. Set original_addresses to addresses you used at the old provider so sent mail is classified as outbound. Imports are marked read by default.

created = inkbox.mailboxes.imports.create(
    "my-agent@inkboxmail.com",
    original_addresses=["old-address@example.com"],
)
inkbox.mailboxes.imports.upload(created.upload, "archive.mbox")
inkbox.mailboxes.imports.start(
    "my-agent@inkboxmail.com", str(created.job.id),
)
job = inkbox.mailboxes.imports.wait(
    "my-agent@inkboxmail.com", str(created.job.id),
)

import { openAsBlob } from "node:fs";

const file = await openAsBlob("archive.mbox");
const created = await inkbox.mailboxes.imports.create(
  "my-agent@inkboxmail.com",
  { originalAddresses: ["old-address@example.com"] },
);
await inkbox.mailboxes.imports.upload(created.upload, file);
await inkbox.mailboxes.imports.start(
  "my-agent@inkboxmail.com", created.job.id,
);
const job = await inkbox.mailboxes.imports.wait(
  "my-agent@inkboxmail.com", created.job.id,
);

inkbox mailbox imports run my-agent@inkboxmail.com archive.mbox \
--original-address old-address@example.com

wait returns completed, failed, or cancelled jobs; a local timeout does not cancel processing. To stop an active job, call cancel or run inkbox mailbox imports cancel <email> <job-id>. Track the independent messages_imported, messages_skipped_duplicate, messages_failed, and messages_rejected_unsafe counters rather than calculating a percentage. Unsafe messages are rejected while the rest of the import continues when possible. See Mail imports for polling, limits, job fields, and all endpoints.

Drafting email

Save incomplete email in the Inkbox Console or through REST, reopen it from the same inbox, and send only the revision you reviewed. Drafts autosave in the Console, count toward inbox storage, and stay outside ordinary message, thread, and search results until sent. Connected mail apps share the same Drafts folder. Every API mutation carries a generation so concurrent edits are detected rather than silently overwritten. A send rejected before delivery is attempted leaves the draft editable. If delivery cannot be confirmed, the draft becomes read-only and must be duplicated or deleted instead of retried automatically. See Email drafts for Console, REST, conflict, storage, and mail-app workflows, or the Drafts REST reference for every endpoint and field.

Custom email signatures

Give each mailbox its own plain-text or HTML signature on a paid plan. Inkbox adds it automatically to outgoing messages, replies, forwards, and draft sends, including mail sent over SMTP. The signature toggle is separate from the organization’s Sent via Inkbox footer setting. See Custom email signatures to configure a signature in the Console, SDK, CLI, or API.

Sending email

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

sent = identity.send_email(
    to=["user@example.com"],
    subject="Hello from Inkbox",
    body_text="Hi there!",
    body_html="<p>Hi there!</p>",
    cc=["manager@example.com"],
    bcc=["archive@example.com"],
)

const sent = await identity.sendEmail({
  to: ["user@example.com"],
  subject: "Hello from Inkbox",
  bodyText: "Hi there!",
  bodyHtml: "<p>Hi there!</p>",
  cc: ["manager@example.com"],
  bcc: ["archive@example.com"],
});

inkbox email send -i my-agent \
--to user@example.com \
--subject "Hello from Inkbox" \
--body-text "Hi there!" \
--body-html "<p>Hi there!</p>" \
--cc manager@example.com \
--bcc archive@example.com

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.

# sent.message_id comes from a previously sent or received message
identity.send_email(
    to=["user@example.com"],
    subject=f"Re: {sent.subject}",
    body_text="Following up on my earlier message.",
    in_reply_to_message_id=sent.message_id,
)

// sent.messageId comes from a previously sent or received message
await identity.sendEmail({
  to: ["user@example.com"],
  subject: `Re: ${sent.subject}`,
  bodyText: "Following up on my earlier message.",
  inReplyToMessageId: sent.messageId,
});

# Use --in-reply-to with the RFC 5322 Message-ID to reply in-thread
inkbox email send -i my-agent \
--to user@example.com \
--subject "Re: Hello from Inkbox" \
--body-text "Following up on my earlier message." \
--in-reply-to "<20250301120000.abc123@inkboxmail.com>"

Attachments

Pass attachments to the SDK as base64-encoded content with a filename and MIME type. The CLI reads files directly with repeatable --attach flags. For an inline image, set its content_id in Python or contentId in TypeScript and reference it from the HTML body as cid:chart1. The CLI uses --inline-image chart1=chart.png with --body-html.

identity.send_email(
    to=["user@example.com"],
    subject="See attached",
    body_text="Please find the file attached.",
    attachments=[{
        "filename": "report.pdf",
        "content_type": "application/pdf",
        "content_base64": "<base64-encoded-content>",
    }],
)

await identity.sendEmail({
  to: ["user@example.com"],
  subject: "See attached",
  bodyText: "Please find the file attached.",
  attachments: [{
      filename: "report.pdf",
      contentType: "application/pdf",
      contentBase64: "<base64-encoded-content>",
  }],
});

inkbox email send -i my-agent \
  --to user@example.com \
  --subject "See attached" \
  --body-html '<p>Please find the report attached.</p><img src="cid:chart1" alt="Chart">' \
  --attach report.pdf \
  --inline-image chart1=chart.png

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.

# msg.id is the UUID of the original message to forward
identity.forward_email(
    msg.id,
    to=["partner@example.com"],
    body_text="Heads up — see below.",
)

# Preserve full MIME fidelity (inline images, calendar invites, etc.)
identity.forward_email(
    msg.id,
    to=["partner@example.com"],
    mode="wrapped",
)

# Route replies to a different address via Reply-To
identity.forward_email(
    msg.id,
    to=["partner@example.com"],
    reply_to="manager@example.com",
)

// msg.id is the UUID of the original message to forward
await identity.forwardEmail(msg.id, {
  to: ["partner@example.com"],
  bodyText: "Heads up — see below.",
});

// Preserve full MIME fidelity (inline images, calendar invites, etc.)
await identity.forwardEmail(msg.id, {
  to: ["partner@example.com"],
  mode: "wrapped",
});

// Route replies to a different address via Reply-To
await identity.forwardEmail(msg.id, {
  to: ["partner@example.com"],
  replyTo: "manager@example.com",
});

# Forward inline (default)
inkbox email forward <MESSAGE_UUID> -i my-agent \
--to partner@example.com \
--body-text "Heads up — see below."

# Wrapped mode preserves full MIME fidelity
inkbox email forward <MESSAGE_UUID> -i my-agent \
--to partner@example.com \
--mode wrapped

# Drop the original attachments (inline mode only)
inkbox email forward <MESSAGE_UUID> -i my-agent \
--to partner@example.com \
--no-include-original-attachments

Forwards count against the same send rate limits as send_email.

Reply to everyone

For a Companion conversation, use the snapshot’s stored reply_to_message_id with reply-all and retain the exact audience, including the sponsor. A different recipient branch or private reply does not inherit that sponsorship. An out-of-cohort Reply-To can make the Companion reply unavailable. 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.

# msg.id is the UUID of the message to reply to
identity.reply_all_email(
    msg.id,
    body_text="Thanks everyone — looping you all back in.",
)

// msg.id is the UUID of the message to reply to
await identity.replyAllEmail(msg.id, {
  bodyText: "Thanks everyone — looping you all back in.",
});

inkbox email reply-all <MESSAGE_UUID> -i my-agent \
--body-text "Thanks everyone — looping you all back in."

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.

sent = identity.send_email(
    to=["user@example.com"],
    subject="Following up",
    body_html="<p>Just checking in.</p>",
    track_opens=True,
)

# Re-fetch later to see opens
msg = identity.get_message(sent.id)
print(msg.first_opened_at, msg.open_count)

const sent = await identity.sendEmail({
  to: ["user@example.com"],
  subject: "Following up",
  bodyHtml: "<p>Just checking in.</p>",
  trackOpens: true,
});

// Re-fetch later to see opens
const msg = await identity.getMessage(sent.id);
console.log(msg.firstOpenedAt, msg.openCount);

inkbox email send -i my-agent \
--to user@example.com \
--subject "Following up" \
--body-html "<p>Just checking in.</p>" \
--track-opens

Reading the inbox

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

# Iterate all messages — pagination is handled automatically
for msg in identity.iter_emails():
    print(msg.subject, msg.from_address, msg.is_read)

# Filter to only inbound (received) or outbound (sent) messages
for msg in identity.iter_emails(direction="inbound"):
    print(msg.subject)

// Iterate all messages — pagination is handled automatically
for await (const msg of identity.iterEmails()) {
  console.log(msg.subject, msg.fromAddress, msg.isRead);
}

// Filter to only inbound (received) or outbound (sent) messages
for await (const msg of identity.iterEmails({ direction: "inbound" })) {
  console.log(msg.subject);
}

# List all messages
inkbox email list -i my-agent

# Filter to only inbound (received) messages
inkbox email list -i my-agent --direction inbound

# Get the full body of a specific message
inkbox email get msg_abc123 -i my-agent

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.

# Process only new messages
unread_ids = []
for msg in identity.iter_unread_emails():
    print(msg.subject)
    unread_ids.append(msg.id)

# Mark them read so they won't appear again on the next run
identity.mark_emails_read(unread_ids)

// Process only new messages
const unreadIds: string[] = [];
for await (const msg of identity.iterUnreadEmails()) {
  console.log(msg.subject);
  unreadIds.push(msg.id);
}

// Mark them read so they won't appear again on the next run
await identity.markEmailsRead(unreadIds);

# List only unread messages
inkbox email unread -i my-agent

# Mark specific messages as read
inkbox email mark-read -i my-agent msg_abc123 msg_def456

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.

Threads

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.

# thread_id is available on any message object
thread = identity.get_thread(msg.thread_id)
for m in thread.messages:
    print(m.from_address, m.subject)

// threadId is available on any message object
const thread = await identity.getThread(msg.threadId!);
for (const m of thread.messages) {
  console.log(m.fromAddress, m.subject);
}

# Get all messages in a thread
inkbox email thread thread_abc123 -i my-agent

Filtering inbound mail

Control incoming and outgoing mail with filter modes and contact rules on the agent identity, addressed by agent_handle. For a simple shared policy, set mail_filter_mode and omit rule direction. New rules cover both sending and receiving. Each identity has a mail_filter_mode field with two values:

blacklist (default). Without an exact-address choice, matching block domains deny communication; otherwise it is permitted.
whitelist. Without an exact-address choice, matching allow domains permit communication; otherwise it is denied.

Mail rules match on exact_email (e.g. jane@acme.example) or domain (e.g. acme.example). Each rule has an action: allow or block. When both match, the exact-address rule takes precedence over the domain rule. The following write examples require an admin API key. You can also manage rules in the Inkbox Console; agent keys cannot create, update, or delete rules. 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.

# Switch an identity to whitelist mode
inkbox.get_identity("my-agent").update(mail_filter_mode="whitelist")

# Back to blacklist (the default)
inkbox.get_identity("my-agent").update(mail_filter_mode="blacklist")

# Block a single spam sender on this identity
inkbox.mail_identity_contact_rules.create(
    "my-agent",
    action="block",
    match_type="exact_email",
    match_target="spammer@spam.example",
)

# Block an entire domain
inkbox.mail_identity_contact_rules.create(
    "my-agent",
    action="block",
    match_type="domain",
    match_target="spam.example",
)

# In whitelist mode: allow one known sender
inkbox.mail_identity_contact_rules.create(
    "my-agent",
    action="allow",
    match_type="exact_email",
    match_target="vendor@acme.example",
)

# Change a rule's action
inkbox.mail_identity_contact_rules.update(
    "my-agent", rule_id, action="block",
)

# Rules on one identity
rules = inkbox.mail_identity_contact_rules.list("my-agent", action="block")

# Org-wide rules (admin-only) — handy for compliance reviews
everything = inkbox.mail_identity_contact_rules.list_all(action="block")

// Switch an identity to whitelist mode (admin-only)
await (await inkbox.getIdentity("my-agent")).update({
  mailFilterMode: "whitelist",
});

// Back to blacklist (the default)
await (await inkbox.getIdentity("my-agent")).update({
  mailFilterMode: "blacklist",
});

// Block a single spam sender on this identity
await inkbox.mailIdentityContactRules.create("my-agent", {
  action: "block",
  matchType: "exact_email",
  matchTarget: "spammer@spam.example",
});

// Block an entire domain
await inkbox.mailIdentityContactRules.create("my-agent", {
  action: "block",
  matchType: "domain",
  matchTarget: "spam.example",
});

// In whitelist mode: allow one known sender
await inkbox.mailIdentityContactRules.create("my-agent", {
  action: "allow",
  matchType: "exact_email",
  matchTarget: "vendor@acme.example",
});

// Change a rule's action
await inkbox.mailIdentityContactRules.update("my-agent", ruleId, {
  action: "block",
});

// Rules on one identity
const rules = await inkbox.mailIdentityContactRules.list("my-agent", {
  action: "block",
});

// Org-wide rules (admin-only) — handy for compliance reviews
const everything = await inkbox.mailIdentityContactRules.listAll({ action: "block" });

# Switch an identity to whitelist mode
inkbox identity update my-agent --mail-filter-mode whitelist

# Block a single sender
inkbox identity mail-rules create my-agent \
--action block --match-type exact_email --match-target spammer@spam.example

# Block a whole domain
inkbox identity mail-rules create my-agent \
--action block --match-type domain --match-target spam.example

# Allow a sender (useful in whitelist mode)
inkbox identity mail-rules create my-agent \
--action allow --match-type exact_email --match-target vendor@acme.example

# Change a rule's action
inkbox identity mail-rules update my-agent <rule-id> --action block

# List rules on one identity
inkbox identity mail-rules list my-agent --action block

Receive broadly, send selectively

With SDK/CLI 0.7.3 or later, choose independent defaults. Inbound is from a sender to your agent; outbound is from your agent to a recipient. This example permits unmatched inbound senders and permits outbound mail only to approved addresses. Existing applicable rules still take precedence.

identity = inkbox.get_identity("my-agent")
identity.update(
    mail_inbound_filter_mode="blacklist",
    mail_outbound_filter_mode="whitelist",
)
rule = inkbox.mail_identity_contact_rules.create(
    "my-agent", action="allow", match_type="exact_email",
    match_target="recipient@example.com", direction="outbound",
)
rules = inkbox.mail_identity_contact_rules.list("my-agent", direction="outbound")

import { MailRuleAction, MailRuleMatchType } from "@inkbox/sdk";

const identity = await inkbox.getIdentity("my-agent");
await identity.update({
  mailInboundFilterMode: "blacklist", mailOutboundFilterMode: "whitelist",
});
const rule = await inkbox.mailIdentityContactRules.create("my-agent", {
  action: MailRuleAction.ALLOW, matchType: MailRuleMatchType.EXACT_EMAIL,
  matchTarget: "recipient@example.com", direction: "outbound",
});
const rules = await inkbox.mailIdentityContactRules.list("my-agent", { direction: "outbound" });

use inkbox::{ContactRuleCreateOptions, ContactRuleDirection, ContactRuleListOptions};
use inkbox::identities::IdentityFilterModeOptions;
use inkbox::mail::{FilterMode, MailRuleAction, MailRuleMatchType};

inkbox.identities().update_filter_modes("my-agent", &IdentityFilterModeOptions {
    mail_inbound_filter_mode: Some(FilterMode::Blacklist),
    mail_outbound_filter_mode: Some(FilterMode::Whitelist),
    ..Default::default()
})?;
let rule = inkbox.mail_identity_contact_rules().create_with_options(
    "my-agent", &ContactRuleCreateOptions {
        action: MailRuleAction::Allow,
        match_type: MailRuleMatchType::ExactEmail,
        match_target: "recipient@example.com".into(),
        direction: Some(ContactRuleDirection::Outbound),
    },
)?;
let rules = inkbox.mail_identity_contact_rules().list_with_options(
    "my-agent", &ContactRuleListOptions {
        direction: Some(ContactRuleDirection::Outbound),
        ..Default::default()
    },
)?;
println!("{} {:?} {}", rule.rule.id, rule.direction, rules.len());

inkbox identity update my-agent \
  --mail-inbound-filter-mode blacklist --mail-outbound-filter-mode whitelist
inkbox identity mail-rules create my-agent --action allow \
  --match-type exact_email --match-target recipient@example.com --direction outbound
inkbox identity mail-rules list my-agent --direction outbound

The outbound list includes both rules. A successful create can widen an existing rule, so retain the returned ID and direction. See rule consolidation and atomic one-side edits.

Rules for an address with whitelist in both directions	Receive	Send
None	Denied	Denied
Allow inbound	Allowed	Denied
Allow outbound	Denied	Allowed
Allow both	Allowed	Allowed

Receiving a message does not authorize a reply. Returning to mail_filter_mode sets both defaults but preserves every rule’s action and direction. Read the effective directional fields rather than reconstructing split state from the shared mode. Response notices can explain that distinction alongside results.

Inspecting mailboxes

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.

# List all mailboxes in the organisation
mailboxes = inkbox.mailboxes.list()

# Get a specific mailbox by email address
mailbox = inkbox.mailboxes.get("sales-bot@inkboxmail.com")

# Full-text search across all messages in a mailbox
results = inkbox.mailboxes.search(mailbox.email_address, q="invoice", limit=20)
for msg in results:
    print(msg.subject, msg.from_address)

// List all mailboxes in the organisation
const mailboxes = await inkbox.mailboxes.list();

// Get a specific mailbox by email address
const mailbox = await inkbox.mailboxes.get("sales-bot@inkboxmail.com");

// Full-text search across all messages in a mailbox
const results = await inkbox.mailboxes.search(mailbox.emailAddress, { q: "invoice", limit: 20 });
for (const msg of results) {
  console.log(msg.subject, msg.fromAddress);
}

# List all mailboxes in the organisation
inkbox mailbox list

# Get a specific mailbox by email address
inkbox mailbox get sales-bot@inkboxmail.com

# Full-text search across all messages
inkbox email search -i support-bot -q "invoice" --limit 20

Use a mail app

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.

Retry a message request

The SDK preserves a generated request key during bounded retries. An explicit idempotency_key (Python), idempotencyKey (TypeScript), or --idempotency-key (CLI) identifies the same intended email across separate calls. A completed retry returns its original response. Read the message for current delivery status. See message send retries and ID lookup.

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

Importing email history

Drafting email

Custom email signatures

Sending email

Branding footer

Threaded replies

Attachments

Forwarding

Reply to everyone

Tracking opens

Reading the inbox

Threads

Filtering inbound mail

Receive broadly, send selectively

Inspecting mailboxes

Use a mail app

Retry a message request

​Importing email history

​Drafting email

​Custom email signatures

​Sending email

​Branding footer

​Threaded replies

​Attachments

​Forwarding

​Reply to everyone

​Tracking opens

​Reading the inbox

​Threads

​Filtering inbound mail

​Receive broadly, send selectively

​Inspecting mailboxes

​Use a mail app

​Retry a message request

Importing email history

Drafting email

Custom email signatures

Sending email

Branding footer

Threaded replies

Attachments

Forwarding

Reply to everyone

Tracking opens

Reading the inbox

Threads

Filtering inbound mail

Receive broadly, send selectively

Inspecting mailboxes

Use a mail app

Retry a message request