Integration Guide

AgentMail + mailbox.bot

Give an agent a digital thread and a physical workflow layer. AgentMail is the email inbox, thread state, and live conversation surface. mailbox.bot handles the moments when the workflow should become a mailed agreement packet, notary request, permit response, certified notice, or other proof-backed physical action.

Best first workflow

A contract, signed packet, notary request, permit response, inspection follow-up, licensing thread, insurance request, or government notice starts in AgentMail. mailbox.bot then handles the physical side whenever the workflow should become printed, mailed, tracked, and approved.

Why This Pairing Works

AgentMail already gives each agent a real inbox and conversation thread. mailbox.bot handles the moment the workflow needs a verified return address, physical delivery, proof, and a human approval checkpoint. That keeps the digital workflow fast while unlocking paper-native actions that email alone cannot finish cleanly.

Use AgentMail For

Inbound email, reply chains, attachments, thread state, labels, and domain-branded reachability.

Use mailbox.bot For

Mailing the formal packet, pricing the send with dry_run=true, requiring approval, and returning mailed or delivered proof to the same app.

Workflow Shapes

Good fits include agreement negotiation that ends in a mailed packet, signature or notary requests, demand or compliance letters, permit and inspection responses, insurance document requests, vendor onboarding packets, and any workflow where email carries the conversation but physical mail carries the finality.

Before You Run

Keep the pairing simple: AgentMail owns the inbox identity and mailbox.bot owns the physical action.

text
1. Create or choose an AgentMail inbox for the workflow.
2. Use a custom domain if the agent should look like part of the business.
3. Subscribe your app to AgentMail message events.
4. Create a mailbox.bot agent credential with mail.send and webhook.manage.
5. Start mailbox.bot with an sk_agent_test_ key and dry_run=true.
6. Require approval before live certified, high-value, time-sensitive, or proof-sensitive mail.

Recommended AgentMail Events

Start with the events that naturally imply a postal step or a thread-state update.

text
message.received
message.delivered
message.bounced
message.rejected

Recommended Label Policy

Use labels to keep the email thread and the postal workflow in sync. The names matter less than having a stable state machine.

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

Workflow Trigger

One useful pattern is: receive or send email in AgentMail, watch for approval, deadline, attachment, bounce, or policy signals, then create a mailbox.bot draft with the email lineage attached in metadata.

mailbox.bot Metadata

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"
}

Webhook Handler Shape

The app listens to AgentMail, applies labels, drafts postal mail with mailbox.bot, and then listens for mailbox.bot delivery updates to close the loop.

ts
export async function handleAgentMailEvent(event: AgentMailEvent) {
  const type = event.event_type;

  if (type === "message.bounced" || type === "message.rejected") {
    await addThreadLabels(event.inbox_id, event.thread_id, ["needs-postal", "deadline"]);

    await createMailboxDraft({
      recipient_name: "County Health Department",
      mail_class: "certified",
      dry_run: true,
      requires_approval: true,
      metadata: {
        source: "agentmail",
        agentmail_inbox_id: event.inbox_id,
        agentmail_thread_id: event.thread_id,
        agentmail_message_id: event.message_id,
      },
    });
  }

  if (type === "message.received") {
    await classifyThreadFromEmail(event.message);
  }

  if (type === "message.delivered") {
    await maybePreparePostalWorkflowFromThread(event.thread_id);
  }
}

Delivery Updates Back To The Email Workflow

mailbox.bot should call your app when the mailpiece is pending approval, submitted, mailed, delivered, or failed. That gives the AgentMail thread a clean handoff back into the original workflow.

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"
  ]
}

Best Vertical Fits

Response packets, renewal threads, signed document bundles, vendor packets, proof-sensitive notices, and any workflow where email is the first touch but hard-copy proof is the serious touch.

Identity Layer

The strongest brand story is simple: your agent is reachable at a custom-domain AgentMail inbox, and when the situation demands it, it can also send approved physical mail from a verified mailbox.bot return address.

Keep llms.txt lean. Put the richer retrieval surface in llms-full.txt and the markdown mirror at agentmail-integration.md.