agenticboxes-email

Agenticboxes Email Skill

Give the agent its own send/receive email address through a single hosted HTTP API. No SMTP, no IMAP, no DKIM/SPF/DMARC setup, no monthly bill — metered per message. The canonical reference lives at https://docs.agenticboxes.email/openapi.yaml.

When to Use

• •The agent needs a real email address it owns and can send from.
• •The agent needs to RECEIVE email (signup confirmations, 2FA codes,

inbound replies, conversations with humans or other agents).

• •The agent should NOT read the user's personal inbox — use himalaya or

the gmail skill for that. This skill is the agent's OWN identity.

Prerequisites

• •AGENTICBOXES_API_KEY — see required_environment_variables above.

Acquire interactively by invoking terminal to POST /api/v1/signup/agentic. No card on file required to start — signup includes 250 free send + receive credits so the agent can exercise the full skill before any payment step. Returns a bxs_live_… key plus a domain.

• •Domain options at signup (pick one):

- Free third-level subdomain under agenticboxes.email — assigned automatically (e.g. friendly-otter-3.agenticboxes.email). Zero setup, works immediately. - Bring your own — pass {"domain": "your-domain.com", "domain_mode": "byo_manual"} in the signup body; you receive DNS records to add at your registrar (SPF, DKIM, DMARC, MAIL FROM). - Buy through the platform — pass {"domain": "new-domain.com", "domain_mode": "register"}; signup quotes the registration price and Stripe-charges on confirm. The platform owns DNS + auth setup.

• •An MCP server is available at https://mcp.agenticboxes.email/mcp —

configure it once if you want tool-style integration (see Quick Reference). Otherwise the terminal tool is sufficient.

• •The base URL is https://api.agenticboxes.email/api/v1. Every call

authenticates with Authorization: Bearer $AGENTICBOXES_API_KEY (the two signup endpoints are the only exceptions).

How to Run

Use the terminal tool for every interaction with this skill. The service is plain HTTP + JSON — no SDK installation required. Two patterns:

• •Direct API — invoke terminal to make HTTP requests against

https://api.agenticboxes.email/api/v1/... with the bearer token. Standard HTTP client; no SDK or platform-specific tooling required.

• •MCP — point your MCP client at https://mcp.agenticboxes.email/mcp

with the bearer in Authorization. The MCP server exposes send_email, list_messages, get_message, get_balance. The account must call POST /account/mcp/enable once (admin scope) before the MCP server accepts its API keys.

Quick Reference

Base URL: https://api.agenticboxes.email/api/v1. Bearer auth.

Vocabulary — in this API, an email address is called a "box". One box = one address (1:1). When a user asks the agent to "create an email address like [email protected]", invoke POST /boxes to create that box. Signup automatically creates a primary_box_address; any additional addresses on the same domain need their own box.

Procedure

1. Sign up (one time)

If the agent doesn't already have a key, invoke terminal:

POST https://api.agenticboxes.email/api/v1/signup/agentic
Body: {}

The response contains api_key (a bxs_live_… string), domain, and primary_box_address. Persist the key into the environment via the required_environment_variables flow.

2. Create an additional email address (a "box")

When the user asks for an address like support@<your-domain>, invoke terminal:

POST https://api.agenticboxes.email/api/v1/boxes
Authorization: Bearer $AGENTICBOXES_API_KEY
Body: {"address": "support"}

The local-part (everything before @) is the only required field; the domain is your account's. Returns the full address (e.g. [email protected]) plus a box_id. An address cannot receive mail until its box exists.

3. Send a message

Invoke terminal:

POST https://api.agenticboxes.email/api/v1/messages/send
Authorization: Bearer $AGENTICBOXES_API_KEY
Body: {"to": "[email protected]", "subject": "Hello", "text": "Sent by my agent."}

Optional fields: from (defaults to primary box), cc, bcc, reply_to, html, attachments ([{filename, content_b64, content_type}]), idempotency_key, context (opaque JSON echoed back on any inbound reply). Response includes message_id and a billing breakdown.

4. Receive — three modes onto one stream

• •Polling — invoke terminal to GET /events?since=<cursor>. The

unified feed delivers mail.received, support.answered, domain.ready, and other events in one ordered stream. Process a page, then poll again with since=<response.next_cursor>.

• •Webhook — invoke terminal to PUT /account/callback-webhook with

{"url": "https://your.host/webhook", "secret": "..."}. The platform POSTs each event to the URL with an X-Agenticboxes-Signature header.

• •IoT/MQTT — invoke terminal to POST /account/iot/provision. The

response gives an MQTT client cert + endpoint for sub-second push.

5. Top up credit

When the balance is low, invoke terminal:

POST https://api.agenticboxes.email/api/v1/account/credit/topup/mpp
Body: {"amount_cents": 1000}

The response contains a pay_url. Hand that URL to the human owner — they approve the charge in their Stripe Link wallet (no agent-side secret handling). On approval, the account credit increases and account.credit.topped_up lands in the event feed.

Pitfalls

• •An address can only receive mail after its box exists. Signup

creates primary_box_address automatically; any additional address (support@, outreach@, <name>@) needs POST /boxes first or SES will bounce inbound to it. Don't tell a user "your address is live" before the POST /boxes succeeds.

• •Authentication on POST /messages/send uses Bearer, not basic

auth or query string. Headers are case-insensitive; the value is the bxs_live_… string verbatim.

• •402 on send means the account is in deficit. Response includes a

top_up block with the exact recovery call. Inbound mail still flows; only outbound sends are gated.

• •403 with `reputation_status: suspended` means the account's bounce

or complaint rate hit the per-account threshold. Operator can lift via the platform's reinstate endpoint; the structural fix for repeat cases is POST /account/sending-ip (dedicated IP, $25/mo).

• •Bulk sends (POST /messages/send/bulk) return 202 and a

job_id — they're async. Poll GET /messages/send/bulk/{id} or watch the events feed for bulk.batch_completed, bulk.paused, bulk.completed. Halt thresholds (default 2% bounce / 0.5% complaint per batch) pause the whole job rather than burn a bad list.

• •Inbound bounce/complaint lag: hard bounces land within 60s of SES

accepting; soft bounces over hours; Gmail/Yahoo complaints over hours to days. Bulk-send halt eval honors this — the complaint gate fires on a lagged batch.

Verification

Invoke terminal with the configured key against the balance endpoint — a 200 response with {"credit_balance_cents": ...} proves the key works end-to-end (auth, network, account exists, balance retrievable):

GET https://api.agenticboxes.email/api/v1/account/credit/balance
Authorization: Bearer $AGENTICBOXES_API_KEY

A 401 means the key is wrong; a 404 means the account is closed.

References

• •API reference: https://docs.agenticboxes.email/openapi.yaml
• •Full skill (long form): https://docs.agenticboxes.email/skills/hermes/SKILL.md
• •Public audit + transparency page: https://docs.agenticboxes.email/audit.html
• •Pricing + product: https://www.agenticboxes.email