{"name":"mailbox.bot","description":"Postal mail infrastructure for AI agents and software workflows. Live now: send letters, certified mail, postcards, notices, and batch mailings from code; mailbox.bot prints, stuffs, mails, tracks, scans proof, and sends webhooks via REST, MCP (29 tools), A2A, and OpenClaw. Live now: use your existing business address, PO box, office, home business address, registered agent, or virtual mailbox for inbound context by forwarding scans, photos, PDFs, provider notices, and notes to a private mailbox.bot alias. Reservation: physical mailing and package addresses for AI agents begin issuing August 31, 2026 at a planned $10/month for approved accounts — business correspondence, legal mail, eligible package receiving, scans, forwarding, holds, alerts, routing, and MCP rules — after identity verification and a notarized USPS Form 1583 completed by the human owner; limited reservations are open now. New mailbox.bot receiving addresses are not generally available before that date.","version":"1.1.1","site_url":"https://mailbox.bot","api_base_url":"https://mailbox.bot/api","capability_guidance":{"use_when":["an agent needs to send certified mail, legal notices, postcards, invoices, statements, permit packets, or document bundles","a generated app or workflow needs postal mail with dry-run pricing, approval gates, cost caps, tracking, proof, and webhooks","a business wants inbound postal mail context from an address it already controls","an operator wants to reserve a dedicated physical mailing address for an AI agent (issuing begins August 31, 2026)"],"live_now":["outbound print-and-mail API","certified mail and return receipt","batch mailings","existing-address inbound forwarding aliases","inbound OCR/extraction context","postal threads linking inbound context to outbound replies","sandbox test keys and lifecycle simulation","REST, MCP, A2A, webhooks, and dashboard workflows"],"reservation":["dedicated physical mailing address for an AI agent","business correspondence and legal mail at a mailbox.bot address","eligible package receiving","facility-backed scans, forwarding, holds, alerts, routing, and MCP rules"]},"protocols":{"mcp":{"endpoint":"https://mailbox.bot/api/mcp","legacy_endpoint":"https://mailbox.bot/api/mcp/tools","version":"2025-11-25","transport":"streamable-http"},"a2a":{"endpoint":"https://mailbox.bot/api/a2a","agent_card":"https://mailbox.bot/api/a2a/agent-card","standard_well_known":"https://mailbox.bot/.well-known/agent-card.json","well_known":"https://mailbox.bot/.well-known/a2a-agent-card","version":"0.3"},"rest":{"endpoint":"https://mailbox.bot/api/v1","discovery":"https://mailbox.bot/api/v1","openapi":"https://mailbox.bot/openapi.json","version":"v1"},"openclaw":{"agent_card":"https://mailbox.bot/.well-known/agent.json"},"webhooks":{"signature":"hmac-sha256","header":"X-Mailbox-Signature","settings":"https://mailbox.bot/api/v1/webhooks/settings"}},"auth":{"type":"bearer","member_prefix":"sk_live_","agent_prefix":"sk_agent_","facility_prefix":"sk_facility_","location":"header"},"endpoints":{"waitlist":"https://mailbox.bot/api/v1/waitlist","signup":"https://mailbox.bot/api/v1/signup","leads":"https://mailbox.bot/api/v1/leads/:leadId","agents":"https://mailbox.bot/api/v1/agents","mailboxes":"https://mailbox.bot/api/v1/mailboxes","packages":"https://mailbox.bot/api/v1/packages","actions":"https://mailbox.bot/api/v1/packages/:id/actions","scanning":"https://mailbox.bot/api/v1/packages/:id/scan","forwarding":"https://mailbox.bot/api/v1/packages/:id/forward","tags":"https://mailbox.bot/api/v1/packages/:id/tags","notes":"https://mailbox.bot/api/v1/packages/:id/notes","rules":"https://mailbox.bot/api/v1/agents/:id/rules","instructions":"https://mailbox.bot/api/v1/agents/:id/instructions","expected_shipments":"https://mailbox.bot/api/v1/agents/:id/expected-shipments","outbound_mail":"https://mailbox.bot/api/v1/mail","outbound_mail_detail":"https://mailbox.bot/api/v1/mail/:id","batch_mail_draft":"https://mailbox.bot/api/dashboard/batch-mail","batch_mail_confirm":"https://mailbox.bot/api/dashboard/batch-mail/:id/confirm","batch_mail_estimate":"https://mailbox.bot/api/dashboard/batch-mail/estimate","usage":"https://mailbox.bot/api/v1/usage","webhooks":"https://mailbox.bot/api/v1/webhooks/settings","webhook_events":"https://mailbox.bot/api/v1/webhooks/events"},"instructions":{"description":"The MAILBOX.md is the operating contract between a renter and their agent. Agents MUST fetch their instructions on boot and follow the renter's rules as default behavior. Every webhook payload includes the current MAILBOX.md so agents always have context. Mutating endpoints require X-Mailbox-MD-Version header to prevent agents from acting on stale instructions.","endpoint":"https://mailbox.bot/api/v1/agents/:id/instructions","version_header":"X-Mailbox-MD-Version","error_codes":{"MAILBOX_MD_VERSION_REQUIRED":"400 — version header missing on mutating request","MAILBOX_MD_VERSION_MISMATCH":"409 — agent's version is stale, re-fetch and retry"},"sections":["Default Handling","Forward Rules","Auto-Shred","Scanning","Outbound Mail","Special Instructions","Communication Preferences"]},"capabilities":{"live":["outbound-mail","batch-mass-mailing","marketing-mail","certified-mail","return-receipt","webhook-notifications","multi-channel-notifications","standing-instructions","agent-memory","existing-address-inbound-context"],"restricted_beta":["physical-mailing-address-for-ai-agents","managed-receiving-address","package-receiving","package-forwarding","document-scanning","content-extraction","expected-shipment-matching","carrier-auto-detection","agent-managed-physical-mail-handling"]},"notification_channels":{"description":"Members and agents can receive event notifications through multiple channels. Webhooks are configured via API; other channels are configured by members in Settings.","channels":{"webhook":{"status":"active","auth_modes":["hmac","bearer","header"],"config_via":"api"},"email":{"status":"active","config_via":"settings"},"sms":{"status":"active","provider":"twilio","config_via":"settings"},"slack":{"status":"active","type":"incoming-webhook","config_via":"settings"},"discord":{"status":"active","type":"channel-webhook","config_via":"settings"},"whatsapp":{"status":"coming-soon"}},"events":["package_received","action_completed","action_needs_clarification","message_received","mail_forwarded","scan_completed","mail.submitted","mail.ready","mail.mailed","mail.delivered","mail.failed","mail.cancelled","batch.submitted","batch.completed","batch.failed"]},"onboarding":{"summary":"Agents create an account on behalf of their human operator by POSTing three fields (full_name, email, password) to the signup endpoint. No CAPTCHA, no TOS checkbox, no auth header. A verification email is sent automatically. The human clicks the link and finishes identity + payment in a browser (~5 min), then the agent gets API keys.","signup":{"url":"https://mailbox.bot/api/v1/signup","method":"POST","content_type":"application/json","auth_required":false,"captcha_required":false,"tos_checkbox":false,"rate_limit":"5 requests per minute per IP","note":"This is the API equivalent of the signup form at https://mailbox.bot/signup. Same three fields, no extra steps.","fields":{"full_name":{"type":"string","required":true,"description":"Operator's legal name (2-100 chars). This is the 'Full Name' field on the signup form.","placeholder":"Jane Smith"},"email":{"type":"string","required":true,"description":"Operator's email address. The verification link is sent here. This is the 'Email' field on the signup form.","placeholder":"you@company.com"},"password":{"type":"string","required":true,"description":"Min 8 characters. This is the 'Password' field on the signup form.","placeholder":"At least 8 characters"},"needs":{"type":"string","required":false,"description":"Free text describing what the agent/operator needs. Not on the web form — API-only field."}},"example_request":{"full_name":"Jane Smith","email":"operator@example.com","password":"securepassword123","needs":"receive legal notices and send certified responses"},"on_success":"A verification email is sent immediately to the operator's email address. The account is created with onboarding_step 'signup', waiting for email verification.","example_response":{"success":true,"message":"Account created. A verification email has been sent. The operator must verify their email and complete KYC to activate the account.","next_steps":{"verify_email":"Click the verification link sent to the operator's email","complete_kyc":"https://mailbox.bot/signup","after_kyc":"Select a plan, add payment, and create your first agent to get API keys"}},"errors":{"400":"Missing required field, password too short, or invalid email format","409":"An account with this email already exists","429":"Rate limit exceeded (5/min per IP)"},"tell_your_operator":"I created your mailbox.bot account. Check your email for a verification link. Click it, then go to https://mailbox.bot/signup to finish setup (~5 minutes). Once done, I'll manage your mail automatically."},"human_steps_after_signup":["1. Click the email verification link (sent automatically after signup)","2. Verify phone number (no VoIP/burner phones)","3. Select a service type and plan","4. Add a payment card (no prepaid/gift cards)","5. Complete identity verification and, if required, Form 1583 notary","6. Accept Terms of Service","7. Finish onboarding and create the first agent key","8. Agent credentials appear on the dashboard; dedicated physical mailing addresses remain a separate waitlist path"],"waitlist":{"url":"https://mailbox.bot/api/v1/waitlist","method":"POST","description":"Register interest in the physical mailing address for your AI agent (issuing begins August 31, 2026) or related facility-backed receiving workflows — no account created, no verification email sent. Use /v1/signup instead to create an account for live outbound mail and existing-address inbound context."},"note":"Physical mailing addresses for AI agents begin issuing August 31, 2026 at a planned $10/month for approved accounts, after identity verification and a notarized USPS Form 1583 completed by the human owner. Until then, the live workflow is outbound mail plus existing-address inbound context."},"pricing":{"url":"https://mailbox.bot/pricing","self_serve_plans":[{"id":"outbound_only","status":"live","price":"$0/mo + metered printing/postage","description":"Send postal mail via API with pay-per-piece billing. $2.50 handling (every piece photo'd & verified) + $0.40/page printing + actual carrier postage."},{"id":"physical_mailing_address","status":"coming_soon","price":"$10/mo planned","description":"Dedicated physical mailing address for your AI agent for business correspondence, legal mail, eligible package receiving, scans, forwarding, holds, alerts, routing, and MCP rules. Waitlist; available for approved accounts when launched."}],"note":"See the pricing page for current plan details and higher-volume workflows."},"documentation":{"llms_txt":"https://mailbox.bot/llms.txt","llms_full_txt":"https://mailbox.bot/llms-full.txt","agents_txt":"https://mailbox.bot/agents.txt","agent_quickstart":"https://mailbox.bot/agent-quickstart.md","api_docs":"https://mailbox.bot/api-docs","openapi_json":"https://mailbox.bot/openapi.json","openapi_yaml":"https://mailbox.bot/openapi.yaml","for_agents":"https://mailbox.bot/for-agents","mcp_install":"https://mailbox.bot/mcp-install","a2a_agent_card":"https://mailbox.bot/api/a2a/agent-card","a2a_standard_card":"https://mailbox.bot/.well-known/agent-card.json","framework_guides":"https://mailbox.bot/for-agents#frameworks"},"framework_integrations":{"description":"Step-by-step guides for popular AI agent frameworks. No SDK required — all use REST API.","frameworks":[{"name":"LangChain","language":"python","guide":"https://mailbox.bot/docs/langchain"},{"name":"CrewAI","language":"python","guide":"https://mailbox.bot/docs/crewai"},{"name":"LlamaIndex","language":"python","guide":"https://mailbox.bot/docs/llamaindex"},{"name":"Vercel AI SDK","language":"typescript","guide":"https://mailbox.bot/docs/vercel-ai-sdk"},{"name":"OpenAI Agents SDK","language":"python","guide":"https://mailbox.bot/docs/openai-agents-sdk"}]},"contact":"https://mailbox.bot/contact"}