mailbox.bot

{
  "name": "mailbox.bot",
  "description": "Postal mail API for AI agents. Send letters, certified mail, postcards, and documents from code. Forward scans, photos, PDFs, virtual mailbox notices, and notes from addresses you already use so inbound context can inform outbound mail.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://mailbox.bot/api/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "0.3"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "application/json",
    "text/plain"
  ],
  "defaultOutputModes": [
    "application/json",
    "text/plain"
  ],
  "securitySchemes": {
    "bearerMember": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "sk_live_*",
      "description": "Member-level API key with full account access"
    },
    "bearerAgent": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "sk_agent_*",
      "description": "Agent-scoped API key with per-agent resource access"
    }
  },
  "security": [
    {
      "bearerMember": []
    },
    {
      "bearerAgent": []
    }
  ],
  "provider": {
    "url": "https://mailbox.bot",
    "organization": "mailbox.bot"
  },
  "documentationUrl": "https://mailbox.bot/for-agents",
  "onboarding": {
    "summary": "Agents can create an account on behalf of their human operator by POSTing to the signup endpoint. No auth or captcha required. A verification email is sent automatically. The human completes identity verification and payment in a browser (~5 min), then the agent has full API access.",
    "signup": {
      "url": "https://mailbox.bot/api/v1/signup",
      "method": "POST",
      "content_type": "application/json",
      "auth_required": false,
      "rate_limit": "5/min per IP",
      "required_fields": {
        "email": "Operator email address",
        "password": "Min 8 characters",
        "full_name": "Operator legal name (2-100 chars)"
      },
      "optional_fields": {
        "needs": "What the agent/operator needs (free text)"
      },
      "example": {
        "email": "operator@example.com",
        "password": "securepassword123",
        "full_name": "Jane Smith",
        "needs": "receive legal notices and send certified responses"
      },
      "triggers": "Verification email sent to operator automatically"
    },
    "after_signup": [
      "Operator clicks email verification link",
      "Operator completes phone + identity + payment at https://mailbox.bot/signup",
      "Operator completes onboarding, creates agent credentials, and can reserve a mailbox.bot-issued address spot for the managed-address rollout"
    ],
    "docs": "https://mailbox.bot/agent-quickstart.md"
  },
  "skills": [
    {
      "id": "provision-address",
      "name": "Reserve Real Mailing Address",
      "description": "Reserve a limited spot for a mailbox.bot-issued mailing and package address with street address + mailbox number for an approved operator or agent. Approved address issuance begins August 2026. For generally available inbound context, keep using an existing address and forward scans/PDFs/notes to mailbox.bot.",
      "tags": [
        "address",
        "provisioning",
        "mailbox"
      ],
      "examples": [
        "Create a new mailing address for my agent",
        "Provision a physical address I can use for official correspondence"
      ]
    },
    {
      "id": "receive-packages",
      "name": "Inbound Mail Intake",
      "description": "For approved mailbox.bot-issued mailing address accounts after address issuance: receive inbound mail or packages, capture arrival photos, scan when requested or instructed, OCR/classify labels and documents, and notify the agent by webhook/API/MCP. Generally available inbound context comes from forwarded scans/PDFs/notes.",
      "tags": [
        "packages",
        "receiving",
        "carriers"
      ],
      "examples": [
        "List all mail received this week",
        "Get details for my latest mail item"
      ]
    },
    {
      "id": "package-forwarding",
      "name": "Mail Forwarding",
      "description": "For approved mailbox.bot-issued mailing address accounts after address issuance: forward stored mail items or packages to another address. Choose a carrier and track fulfillment.",
      "tags": [
        "packages",
        "forwarding",
        "shipping"
      ],
      "examples": [
        "Forward mail item PKG-123 to 123 Main St, San Francisco, CA 94102",
        "Ship this item via UPS Ground"
      ]
    },
    {
      "id": "document-scanning",
      "name": "Document Scanning & OCR",
      "description": "For approved mailbox.bot-issued mailing address accounts after address issuance: open items and scan contents, then attach OCR/classification context and notify the agent. For generally available inbound context, upload or forward existing scans/PDFs/photos for OCR-backed extraction.",
      "tags": [
        "documents",
        "ocr",
        "scanning"
      ],
      "examples": [
        "Scan the documents inside package PKG-456",
        "Get OCR results for my scanned package"
      ]
    },
    {
      "id": "package-actions",
      "name": "Package Actions",
      "description": "Request actions on packages: forward, shred, scan, hold, dispose, return to sender, photograph, record video. Unified action queue with priority levels.",
      "tags": [
        "packages",
        "actions",
        "automation"
      ],
      "examples": [
        "Shred package PKG-789",
        "Take a photo of the label on my package",
        "Record a video of package contents"
      ]
    },
    {
      "id": "standing-instructions",
      "name": "Standing Instructions",
      "description": "Create rules that auto-trigger actions when incoming mail matches conditions such as sender, carrier, weight, or tracking prefix.",
      "tags": [
        "rules",
        "automation",
        "standing-instructions"
      ],
      "examples": [
        "Auto-forward all FedEx items over 5 lbs",
        "Shred any mail from sender containing \"marketing\""
      ]
    },
    {
      "id": "expected-shipments",
      "name": "Expected Shipment Matching",
      "description": "Pre-register expected packages. When they arrive, auto-match and optionally trigger an action.",
      "tags": [
        "packages",
        "matching",
        "automation"
      ],
      "examples": [
        "Register expected shipment with tracking 1Z999AA10123456784",
        "Auto-scan any package from Amazon arriving this week"
      ]
    },
    {
      "id": "agent-memory",
      "name": "Agent Memory",
      "description": "Tag and annotate mail items with labels and notes. Persistent context across the full lifecycle.",
      "tags": [
        "memory",
        "tags",
        "notes"
      ],
      "examples": [
        "Tag mail item PKG-321 as \"legal-notice\"",
        "Add a note: reply due within 14 days"
      ]
    },
    {
      "id": "webhook-notifications",
      "name": "Webhook Notifications",
      "description": "HMAC-signed webhook delivery for package events. Configurable event types, carrier filters, and retry logic.",
      "tags": [
        "webhooks",
        "notifications",
        "events"
      ],
      "examples": [
        "Set my webhook URL to https://myagent.com/hooks/mailbox",
        "Subscribe to package.received and action.completed events"
      ]
    },
    {
      "id": "multi-channel-notifications",
      "name": "Multi-Channel Notifications",
      "description": "Deliver event alerts via email, SMS (Twilio), Slack (Incoming Webhook), Discord (Channel Webhook), or webhooks. Members configure channels and per-event toggles in Settings. Events: package_received, action_completed, action_needs_clarification, message_received, mail_forwarded, scan_completed, outbound_submitted, mail.ready, mail.mailed, mail.delivered.",
      "tags": [
        "notifications",
        "email",
        "sms",
        "slack",
        "discord",
        "channels"
      ],
      "examples": [
        "Notify me on Slack when new mail arrives",
        "Send SMS alerts for action clarification requests",
        "Enable Discord notifications for outbound mail status"
      ]
    }
  ]
}