Integration Guide
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.
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.
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.
Inbound email, reply chains, attachments, thread state, labels, and domain-branded reachability.
Mailing the formal packet, pricing the send with dry_run=true, requiring approval, and returning mailed or delivered proof to the same app.
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.
Keep the pairing simple: AgentMail owns the inbox identity and mailbox.bot owns the physical action.
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 or deadline-sensitive mail.Start with the events that naturally imply a postal step or a thread-state update.
message.received
message.delivered
message.bounced
message.rejectedUse labels to keep the email thread and the postal workflow in sync. The names matter less than having a stable state machine.
permit
inspection
deadline
agreement
signature-request
notary
needs-postal
postal-approved
postal-sent
resolvedOne 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.
{
"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"
}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.
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);
}
}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.
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"
]
}Permits, inspections, licensing, insurance follow-ups, landlord and vendor packets, collections, and any workflow where email is the first touch but hard-copy proof is the serious touch.
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.