# AgentMail + mailbox.bot Postal Workflows

> Use AgentMail with mailbox.bot when an agent should start with email and then move into physical mail whenever the workflow needs hard-copy delivery, approval, signatures, notarization, or proof.

Human page: https://mailbox.bot/docs/agentmail
Markdown mirror: https://mailbox.bot/agentmail-integration.md
Full API reference: https://mailbox.bot/llms-full.txt
MCP endpoint: https://mailbox.bot/api/mcp

## Best fit

This pairing is strongest for agreement packets, signature and notary requests, permits, inspections, licensing, insurance follow-ups, landlord or vendor packets, collections, and other operational threads where email is the first touch but paper still matters.

Canonical flow:

1. An agent sends or receives email in AgentMail.
2. The thread is labeled for state such as `deadline`, `inspection`, `agreement`, `signature-request`, `needs-postal`, or `resolved`.
3. If the thread should move into a paper workflow, the app creates a mailbox.bot draft.
4. The mailbox.bot draft uses `dry_run=true` for pricing and validation first.
5. For certified mail or deadline-sensitive workflows, the app sets `requires_approval=true`.
6. mailbox.bot emits webhook events for `mail.pending_approval`, `mail.submitted`, `mail.mailed`, `mail.delivered`, or `mail.failed`.
7. The app writes those results back into the AgentMail-driven workflow, labels, or task state.

## Why this pairing works

AgentMail is the digital inbox, reply chain, and thread-state system. mailbox.bot is the physical execution and proof system.

AgentMail gives an agent:

- a dedicated inbox identity
- thread-aware email conversations
- labels for workflow state
- event-driven webhooks
- custom-domain inboxes for brand trust
- inbox-scoped keys for narrow access

mailbox.bot adds:

- first-class and certified mail
- no-charge cost previews with `dry_run=true`
- approval gates with `requires_approval=true`
- proof packs and delivery state
- webhook events that can update the original workflow

## Workflow shapes

- agreement negotiation that ends in a mailed packet
- signature or notary requests
- permit and inspection responses
- compliance letters and deadline notices
- insurance or vendor document packets
- collections or landlord paperwork
- any thread where email carries the conversation but physical mail carries the finality

## Recommended AgentMail events

- `message.received`
- `message.delivered`
- `message.bounced`
- `message.rejected`

These are enough for a first version:

- `message.received`: classify the workflow and attach labels
- `message.delivered`: mark the digital thread as active and decide whether it should later become a mailed packet
- `message.bounced`: use postal when delivery still matters
- `message.rejected`: flag policy or validation failure, then decide whether a mailed workflow is still allowed

## Recommended label policy

Use a stable thread-state convention:

- `permit`
- `inspection`
- `deadline`
- `agreement`
- `signature-request`
- `notary`
- `needs-postal`
- `postal-approved`
- `postal-sent`
- `resolved`

## mailbox.bot metadata

Store email lineage on the mail job so the physical send can always be traced back to the digital thread:

```json
{
  "source": "agentmail",
  "integration": "agentmail",
  "workflow": "agreement_packet_or_compliance_mail",
  "agentmail_inbox_id": "permits@ops.yourco.com",
  "agentmail_thread_id": "thd_123",
  "agentmail_message_id": "<msg_123@ops.yourco.com>",
  "agency": "County Health Department",
  "deadline": "2026-06-12",
  "case_number": "HD-2026-1042",
  "document_type": "signed_agreement_packet"
}
```

## App architecture

1. AgentMail webhook hits your app.
2. Your app reads the inbox, thread, message, labels, and attachments.
3. Your app decides whether the thread should stay digital or become a physical-mail workflow.
4. Your app calls mailbox.bot with `dry_run=true`.
5. A human approves live certified or deadline-sensitive mail.
6. mailbox.bot webhook updates the same app.
7. Your app updates the AgentMail-side workflow state.

## mailbox.bot webhook setup

```http
PUT /api/v1/webhooks/settings
Authorization: Bearer sk_agent_...
Content-Type: application/json

{
  "webhook_url": "https://your-app.example.com/mailboxbot/webhook",
  "enabled": true,
  "event_types": [
    "mail.pending_approval",
    "mail.submitted",
    "mail.mailed",
    "mail.delivered",
    "mail.failed"
  ]
}
```

## Safety defaults

- use `dry_run=true` first
- use `requires_approval=true` for certified mail, deadlines, disputes, and government workflows
- store AgentMail inbox, thread, and message IDs in `metadata`
- keep `llms.txt` lean and put richer integration detail here and in `llms-full.txt`

## Keywords for retrieval

AgentMail postal workflows, AgentMail agreement packet, AgentMail signature request by mail, AgentMail notary request workflow, AgentMail physical mail proof, email thread to postal workflow, permit email to certified mail, inspection follow-up by postal mail, AgentMail mailbox.bot integration, custom-domain email plus postal address, mailbox.bot AgentMail webhook workflow.