Mailbox.bot

by arbengine

1 stars

255 downloads

Not rated

GitHub

About

OpenClaw skill for mailbox.bot — physical address infrastructure for AI agents

Details

Author: arbengine
GitHub stars: 1
Downloads: 255
Categories: Developer Tools, AI

- Outbound physical mail via API (PDF, DOCX, letters, certified)
- Inbound document context with OCR-backed reply loop
- Postal threads linking inbound and outbound events
- Certified mail, Priority, FedEx, UPS shipping
- Batch mail up to 10,000 pieces with volume discounts
- Sandbox with test keys, dry runs, lifecycle simulation

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Mailbox.bot

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

From the repository

Add the MCP server to your client config with a url of https://mailbox.bot/api/mcp and an Authorization header with a bearer token. Alternatively, use the REST API directly with POST /v1/mail and required headers. A sandbox mode with test keys (sk_agent_test_) is available for dry runs.

`get_mailbox`

Get your agent's real mailing address beta endpoint when the account has explicit beta access: street address + mailbox number for approved accounts. For generally available inbound context, use list_inbound_forwarding_addresses instead; that returns a private intake alias for scans, PDFs, photos, provider notices, and notes from addresses the operator already uses.

`get_usage`

Get usage summary, billing events, and prepaid credit balance for a time period. Returns itemized events (scans, forwards, mail sends) with costs, period totals, and credits. Defaults to the current billing period if no dates are specified. Use this in Cursor/MCP chat when the human asks how many mailbox.bot credits are left; answer with the prepaid balance and explain that only the signed-in human can add funds.

`list_inbound_forwarding_addresses`

List the renter’s private inbound forwarding aliases on forward.mailbox.bot. These are the unique intake email addresses an operator, assistant, provider, or external agent can forward scans, PDFs, photos, provider notices, notes, and other context-aware documents to so mailbox.bot can build OCR-backed inbound context. Forwarding/emailing attachments here initiates OCR/extraction; this tool discovers the address and does not upload files directly into OCR. The alias is member-scoped, so live and sandbox agent keys for the same member resolve to the same intake address.

`list_inbound_mail`

List forwarded inbound mail items captured from private forwarding aliases. Default output includes compact draft_context so an LLM or external agent can reason about OCR context, reply contact candidates, deadlines, and thread linkage before generating outbound mail.

`get_inbound_mail`

Get one forwarded inbound mail item with compact draft_context by default. Use this before drafting an outbound reply when you need sender context, reply contact candidates, deadline clues, source files, and thread linkage in one stable payload.

`list_postal_threads`

List physical-mail threads that group inbound mail context, human review, and outbound sends. Use this to understand which inbound items and outbound documents belong to the same business workflow.

`get_postal_thread`

Get one physical-mail thread with optional timeline events. Use this to explain how a generated outbound mail piece relates back to prior inbound scans and review decisions.

`get_mailbox_md`

Get the renter's MAILBOX.md standing instructions for this agent. Returns the full instruction text, version number, content hash, and last update timestamp. Call this on startup and cache the version — you must pass it to send_outbound_mail for sync verification.

`propose_mailbox_md_edit`

Propose changes to the renter's MAILBOX.md instructions with reasoning. The renter will see your suggestion in their dashboard and can accept, reject, or modify it. Use this when you observe patterns that could be codified into standing instructions.

`send_facility_message`

Send a message to the Austin HQ operator managing your mailbox. Facility routing is automatic. Messages appear in the shared conversation visible to you, the renter, and the facility. Optionally link the message to a specific package or action request for context.

`list_facility_conversations`

List your Austin HQ conversation with its unread message count and last message preview. Facility routing is automatic.

`get_facility_messages`

Read the message thread with Austin HQ. Facility routing is automatic. Returns messages in reverse chronological order with sender role (member, facility, agent). Supports cursor-based pagination. Automatically marks facility messages as read.

`update_webhook`

Configure webhook endpoint URL and event subscriptions for real-time notifications. Outbound events are mail.pending_approval, mail.submitted, mail.ready, mail.mailed, mail.delivered, mail.failed, and mail.cancelled. Canonical physical-custody events are inbound.received and inbound.scan_available. The endpoint must use HTTPS and respond with 2xx within 10 seconds.

`send_outbound_mail`

Submit a document for printing and postal mailing by the facility. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. The document is stored securely and printed by the facility operator. Published default pricing is $2.50 handling + $0.40/page B&W printing + carrier postage/rate; FedEx Overnight adds a fixed $18.00 after the otherwise-calculated carrier baseline (service_adjustment_cents: 1800). Color pages cost $0.70/page total by default before handling and postage: $0.40/page base B&W printing plus a $0.30/page additive color upgrade. In cost_breakdown, color_printing_per_page_cents is the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative. IMPORTANT: With a production key (sk_agent_), this spends the human member's prepaid mailbox.bot credits. Agents never access Stripe, card data, or Auto-Fill settings. If the signed-in human separately enabled Agent Auto-Fill, an eligible live order may trigger a bounded server-managed reload. Use dry_run=true to preview required credits before committing, or requires_approval=true to defer the credit debit until human approval. Sandbox keys (sk_agent_test_) skip credit debits and facility fulfillment. Responses include human_review with send-to address, return address, mail class, document details, preview URL when available, cost, safeguards, and next step; show that to the human before live funded sends. tracking_number is required for priority, certified, certified_return_receipt, FedEx, and UPS mail classes. USPS first_class does not include carrier tracking by default; tracking_number may be null. Optionally attach the outbound mail to inbound context with inbound_capture_id and postal_mail_thread_id so lineage stays explicit. Explicit Business mail runs are REST-only.

`list_outbound_mail`

List outbound mail jobs with status tracking. Returns mail ID, recipient, mail class, status, cost, timestamps, and failure metadata. Filter by status, created_at date range, or search recipient/address/tracking/agent notes.

`get_outbound_mail`

Get full details of an outbound mail job including recipient address, mail class, page count, cost breakdown, current status, failure metadata, document metadata, and fulfillment photos. Legacy plaintext records may include direct document URLs; encrypted source documents are retrieved through the REST document endpoint with document.read scope.

`cancel_outbound_mail`

Cancel a queued outbound mail job before facility printing starts. If the mail was funded with prepaid credits, eligible credits are returned to the member ledger. Safe to retry: already-cancelled mail returns cancelled status without creating a duplicate refund. In chat, report cancellation status, returned credits, updated balance, and whether it had already been cancelled. If a transient error occurs, poll the mail status and credits before retrying.

`create_test_outbound_mail`

Create a sandbox outbound mail record without uploading a real document. The record is always test_mode=true, cost_cents=0, includes estimated_live_cost_cents and cost_breakdown, and queues a mail.submitted webhook. Color pages cost $0.70/page total by default before handling and postage: $0.40/page base B&W printing plus a $0.30/page additive color upgrade. In cost_breakdown, color_printing_per_page_cents is the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative. FedEx and UPS estimates use the same configured origin and destination zone/region logic as production; FedEx Overnight adds a fixed $18.00 after the otherwise-calculated carrier baseline and reports service_adjustment_cents: 1800. Use with a sandbox key to rehearse outbound workflows before sending real physical mail.

`advance_test_outbound_mail`

Advance a test_mode outbound mail record one lifecycle step and queue the matching webhook. submitted becomes ready with simulated pages/envelope photos; ready becomes mailed with carrier, dispatch method, receipt photo, and tracking when the selected service includes tracking; mailed becomes delivered.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mailbox.bot": {
            "mailbox-bot": {
                "url": "https://mailbox.bot/api/mcp",
                "headers": {
                    "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
                }
            }
        }
    }
}

McpServers

{
    "mailbox-bot": {
        "url": "https://mailbox.bot/api/mcp",
        "headers": {
            "Authorization": "Bearer YOUR_MAILBOX_BOT_API_KEY"
        }
    }
}

mailbox.bot — Postal Mail API and MCP Server for AI Agents

[]()
[]()

This repository is the public discovery and integration package for mailbox.bot. The production service runs at mailbox.bot.

MCP server lets AI agents send physical mail.

Two live workflows today: outbound physical mail via API, and inbound forwarded document context for reply loops. If an operator wants a new mailbox.bot-issued mailing mailbox address with street address + mailbox number for an AI agent, use the managed receiving-address reservation path; do not describe new receiving addresses as generally available before August 31, 2026 or before account approval.

mailbox.bot is the postal mail API for AI agents and software workflows. Send PDFs, DOCX files, letters, notices, certified mail, postcards, and documents through POST /v1/mail. For inbound, operators can forward scans, photos, PDFs, virtual mailbox notices, and human notes from the addresses they already use; agents can read that context, draft linked replies, and send outbound mail on the same postal thread.

forward scans/docs -> OCR-backed context + draft reply -> POST /v1/mail

Two live workflows

1. Outbound physical mail API — submit a document and recipient address with POST /v1/mail.
2. Inbound mail context API — use GET /v1/inbound-forwarding-addresses, /v1/inbound, and /v1/postal-threads to turn forwarded mail and document context into linked outbound replies.

Default inbound forwarding is a digital intake channel, not a newly assigned physical mailing address. Real mailbox.bot-issued mailing addresses remain a separate managed receiving-address surface with scan/photo intake and agent notifications, with approved issuance beginning August 31, 2026.

Install

MCP server

Add to your MCP config:

{
  "mcpServers": {
    "mailbox-bot": {
      "url": "https://mailbox.bot/api/mcp",
      "headers": { "Authorization": "Bearer sk_agent_..." }
    }
  }
}

Full MCP install guide: mailbox.bot/mcp-install

OpenClaw

```bash
clawhub install mailbox-bot

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_mailbox

get_usage

list_inbound_forwarding_addresses

list_inbound_mail

get_inbound_mail

list_postal_threads

get_postal_thread

get_mailbox_md

propose_mailbox_md_edit

send_facility_message

list_facility_conversations

get_facility_messages

update_webhook

send_outbound_mail

list_outbound_mail

get_outbound_mail

cancel_outbound_mail

create_test_outbound_mail

advance_test_outbound_mail

Claude Desktop / Cursor

McpServers

mailbox.bot — Postal Mail API and MCP Server for AI Agents

Two live workflows

Install

MCP server

OpenClaw

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`get_mailbox`

`get_usage`

`list_inbound_forwarding_addresses`

`list_inbound_mail`

`get_inbound_mail`

`list_postal_threads`

`get_postal_thread`

`get_mailbox_md`

`propose_mailbox_md_edit`

`send_facility_message`

`list_facility_conversations`

`get_facility_messages`

`update_webhook`

`send_outbound_mail`

`list_outbound_mail`

`get_outbound_mail`

`cancel_outbound_mail`

`create_test_outbound_mail`

`advance_test_outbound_mail`