Email

Wirebox provides autonomous AI agents with full email capabilities. Each agent identity automatically receives a dedicated, persistent email address to exchange messages with human users, external services, and other AI systems.

Dedicated Mailbox Addresses

When you provision an agent identity (e.g., @eva), Wirebox immediately assigns a production address:

eva@wireboxmail.com

This mailbox can receive incoming emails from any mail provider (Gmail, Outlook, custom corporate domains) and send outbound messages to any valid address on the internet. To send and receive from a domain your organization owns instead, see Custom Domains.

Sending Outbound Email

Agents can initiate email conversations using the Python SDK, TypeScript SDK, or CLI. Wirebox supports both plain text and rich HTML bodies.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    message = eva.send_email(
        to=["user@example.com"],
        subject="Quarterly Performance Report",
        body_text="Hello! Here is your requested report summary...",
        html="<p>Hello! Here is your <strong>requested report summary</strong>...</p>"
    )
    print("Dispatched message ID:", message.id)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

const message = await eva.sendEmail({
  to: "user@example.com",
  subject: "Quarterly Performance Report",
  text: "Hello! Here is your requested report summary...",
  html: "<p>Hello! Here is your <strong>requested report summary</strong>...</p>",
});

console.log("Dispatched message ID:", message.id);

wirebox mail send --identity eva \
  --to user@example.com \
  --subject "Quarterly Performance Report" \
  --text "Hello! Here is your requested report summary..." \
  --html "<p>Hello! Here is your <strong>requested report summary</strong>...</p>"

Reading Inboxes & Polling

Fetch incoming messages from the agent’s dedicated mailbox. Messages arrive fully parsed with headers, plain text, HTML, and attachment metadata.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")

    # 1. Fetch recent messages
    messages = eva.list_messages(limit=10)
    for msg in messages:
        print(f"[{msg.id}] From: {msg.from_address} | Subject: {msg.subject}")

    # 2. Iterate lazily through message history (auto-paginating)
    for msg in eva.iter_emails(limit=50):
        print(f"Processing: {msg.subject}")

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

// 1. Fetch recent messages
const { messages } = await eva.listMessages({ limit: 10 });
for (const msg of messages) {
  console.log(`[${msg.id}] From: ${msg.from} | Subject: ${msg.subject}`);
}

// 2. Iterate lazily through message history (auto-paginating)
for await (const msg of eva.iterMessages({ limit: 50 })) {
  console.log(`Processing: ${msg.subject}`);
}

# Tabular view in terminal
wirebox mail list --identity eva --limit 10

# Raw JSON output for subagent pipelines or jq scripting
wirebox mail list --identity eva --limit 10 --json

# Inspect a single message in detail
wirebox mail get msg_01J8ABC123XYZ --identity eva

Searching Email

Full-text search across a mailbox returns messages ranked by relevance, with a highlight around the best match. Search covers the subject, body, sender, and snippet — useful when an agent needs to find a specific invoice, customer, or thread without fetching the whole inbox.

curl -X GET "https://api.wirebox.sh/api/v1/mailboxes/eva/search?q=invoice%20overdue&limit=10" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")
    for match in eva.search_messages(q="invoice overdue", limit=10):
        print(f"[{match.from_address}] {match.subject}")
        print(match.highlight or match.snippet)

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { messages, count } = await eva.searchMessages({ q: "invoice overdue", limit: 10 });

for (const match of messages) {
  console.log(`[${match.from}] ${match.subject}`);
  console.log(match.highlight ?? match.snippet);
}

wirebox mail search --identity eva --query "invoice overdue" --limit 10

MCP clients can run the same search through the wirebox_mail_search tool — see MCP.

See List & Search Messages for the full parameter and response reference.

Replying to Existing Threads

When an agent replies to a human user, Wirebox maintains RFC 5322 conversation continuity:

Sets In-Reply-To and References headers referencing previous message IDs.
Prefixes the Subject line with Re: if not already present.
Automatically links the response to the existing conversation thread_id.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    eva.send_email(
        to=["user@example.com"],
        subject="Re: Quarterly Performance Report",
        body_text="Hello Alex,\n\nI have adjusted your account limits as requested.\n\nBest,\nEva",
        thread_id="thrd_01J8XYZ987ABC"
    )

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

await eva.replyEmail("msg_01J8ABC123XYZ", {
  text: "Hello Alex,\n\nI have adjusted your account limits as requested.\n\nBest,\nEva",
});

wirebox mail reply msg_01J8ABC123XYZ --identity eva \
  --text "Hello Alex, I have adjusted your account limits as requested. Best, Eva"

Drafting Emails

Some emails need a review pass before they go out. Drafts let an agent compose a message, revise it — optionally with optimistic version checks — and send it later, either as a new email, a reply, or a forward.

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")

    # 1. Compose a draft
    draft = eva.create_draft(
        to=["alex@example.com"],
        subject="Invoice follow-up",
        text="Hi Alex, just checking in on invoice #1042.",
    )

    # 2. Revise it (rejected with 409 if someone else got there first)
    draft = eva.update_draft(
        draft.id,
        version=draft.version,
        text="Hi Alex, invoice #1042 is now overdue.",
    )

    # 3. Send it — the draft becomes a permanent message
    sent = eva.send_draft(draft.id)
    print("Sent message ID:", sent.id)

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");

// 1. Compose a draft
let draft = await eva.createDraft({
  to: ["alex@example.com"],
  subject: "Invoice follow-up",
  text: "Hi Alex, just checking in on invoice #1042.",
});

// 2. Revise it (rejected with 409 if someone else got there first)
draft = await eva.updateDraft(draft.id, {
  version: draft.version,
  text: "Hi Alex, invoice #1042 is now overdue.",
});

// 3. Send it — the draft becomes a permanent message
const sent = await eva.sendDraft(draft.id);
console.log("Sent message ID:", sent.id);

# Compose, revise, then send
wirebox mail draft create --identity eva \
  --to alex@example.com \
  --subject "Invoice follow-up" \
  --text "Hi Alex, just checking in on invoice #1042."

wirebox mail draft update drf_01J8ABC123XYZ \
  --identity eva \
  --expected-version 1 \
  --text "Hi Alex, invoice #1042 is now overdue."

wirebox mail draft send drf_01J8ABC123XYZ --identity eva

Draft attachments are stored in R2 and promoted to permanent message attachments when the draft is sent. See the Email Drafts API reference for the full object schema and error codes.

Forwarding Messages

Forward existing emails to external teammates or services. Wirebox automatically formats the quoted RFC body (---------- Forwarded message ---------), creates an independent conversation thread, and clones original R2 attachments unless disabled (forward_attachments=false or --no-attachments).

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    forwarded = eva.forward_email(
        "msg_01J8ABC123XYZ",
        to=["accounting@example.com"],
        body_text="FYI, forwarding the vendor contract for your review.",
        forward_attachments=True,
    )
    print("Forwarded message ID:", forwarded.id)
    print("New thread ID:", forwarded.thread_id)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

const forwarded = await eva.forwardEmail("msg_01J8ABC123XYZ", {
  to: ["accounting@example.com"],
  body_text: "FYI, forwarding the vendor contract for your review.",
  forward_attachments: true,
});

console.log("Forwarded message ID:", forwarded.id);
console.log("New thread ID:", forwarded.thread_id);

wirebox mail forward msg_01J8ABC123XYZ \
  --to accounting@example.com \
  --comment "FYI, forwarding the vendor contract for your review."

Sending Attachments

Send PDF reports, invoices, images, logs, or data exports alongside your messages.

import base64
from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    with open("./export.pdf", "rb") as f:
        pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

    eva.send_email(
        to=["client@example.com"],
        subject="Exported Dataset",
        body_text="Please find your requested dataset attached below.",
        attachments=[
            {
                "filename": "export.pdf",
                "content_type": "application/pdf",
                "content": pdf_b64
            }
        ]
    )

import * as fs from "node:fs";
import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

const pdfData = fs.readFileSync("./export.pdf").toString("base64");

await eva.sendEmail({
  to: "client@example.com",
  subject: "Exported Dataset",
  text: "Please find your requested dataset attached below.",
  attachments: [
    {
      filename: "export.pdf",
      content_type: "application/pdf",
      content: pdfData,
    },
  ],
});

# The CLI automatically reads, determines MIME type, and base64 encodes the file
wirebox mail send --identity eva \
  --to client@example.com \
  --subject "Exported Dataset" \
  --text "Please find your requested dataset attached below." \
  --attach ./export.pdf

Deleting Messages

Remove messages from the agent’s mailbox when archiving or adhering to data retention policies.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    eva.delete_message("msg_01J8ABC123XYZ")
    print("Message deleted.")

await eva.deleteMessage("msg_01J8ABC123XYZ");
console.log("Message deleted.");

wirebox mail delete msg_01J8ABC123XYZ --identity eva

Mail Guardrails

Every identity can restrict who reaches it and who it can reach. Two mechanisms work together:

Rules — exact allow or block entries for an email address or a domain, scoped to inbound, outbound, reply, or both.
Filter modes (policy) — the baseline posture: blacklist (open, the default) or whitelist (only approved senders or recipients).

Rules are evaluated first: exact email match, then domain match, then reply threading, then the baseline posture. Inbound mail rejected by the guardrails is quarantined and never enters the inbox or triggers an email.received webhook.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")

    # Allow a partner domain, block a known spam domain
    eva.mail_rules.allow("partner.example", direction="inbound")
    eva.mail_rules.block("spam.example", direction="inbound")

    # Require approved senders from now on (baseline posture)
    eva.set_mail_policy(inbound="protected")

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();
const eva = await wb.getIdentity("eva");

// Allow a partner domain, block a known spam domain
await eva.mailRules.allow("partner.example", { direction: "inbound" });
await eva.mailRules.block("spam.example", { direction: "inbound" });

// Require approved senders from now on (baseline posture)
await eva.setMailPolicy({ inbound: "protected" });

# Allow a partner domain, block a known spam domain
wirebox mail rules allow partner.example --identity eva --inbound
wirebox mail rules block spam.example --identity eva --inbound

# Require approved senders from now on (baseline posture)
wirebox mail policy set --identity eva --inbound protected

See the Mail Rules & Policy API reference for the evaluation order, rule fields, and error codes.

Delivery Status Lifecycle

Every outbound message proceeds through a tracked delivery lifecycle:

Status	Meaning
`queued`	Message accepted by Wirebox and queued for dispatch.
`sent`	Dispatched to the recipient mail exchange (MX) server.
`delivered`	Confirmed received by the remote server.
`bounced`	Rejected by the recipient server (invalid address, mailbox full).
`failed`	Outbound delivery failed permanently after edge retries.

If you are writing low-level HTTP clients or webhook receivers, refer to the REST API Reference:

Driving email from an AI client? See the MCP.

Get Started

Capabilities

Integrations

Dedicated Mailbox Addresses

Sending Outbound Email

Reading Inboxes & Polling

Searching Email

Replying to Existing Threads

Drafting Emails

Forwarding Messages

Sending Attachments

Deleting Messages

Mail Guardrails

Delivery Status Lifecycle

​Dedicated Mailbox Addresses

​Sending Outbound Email

​Reading Inboxes & Polling

​Searching Email

​Replying to Existing Threads

​Drafting Emails

​Forwarding Messages

​Sending Attachments

​Deleting Messages

​Mail Guardrails

​Delivery Status Lifecycle

​Related APIs

Dedicated Mailbox Addresses

Sending Outbound Email

Reading Inboxes & Polling

Searching Email

Replying to Existing Threads

Drafting Emails

Forwarding Messages

Sending Attachments

Deleting Messages

Mail Guardrails

Delivery Status Lifecycle

Related APIs