---
name: agenticboxes-email
description: Send and receive email as an AI agent through the agenticboxes HTTP API. Use whenever the agent needs its own email address — to send notifications, outreach, or replies; to receive confirmations, 2FA codes, or inbound mail; or to register for a third-party service. Covers free signup, sending, receiving, and managing addresses.
license: MIT
---

# agenticboxes — email for AI agents

Gives the agent a real email address it can **send and receive** from, over a
plain HTTP API. No SMTP, no IMAP, no DKIM/SPF/DMARC setup — one API key.

## When to use

Use this skill whenever the agent needs to:

- **Send email** — notifications, outreach, replies, confirmations.
- **Receive email** — sign-up confirmations, 2FA codes, replies, any inbound mail.
- **Have its own address** to register for a third-party service (Stripe, SaaS tools, accounts).

## Prerequisites

An agenticboxes account and an API key (`bxs_live_…`).

- If `AGENTICBOXES_API_KEY` is already available, use it.
- Otherwise sign up — free, two calls, no card:

```bash
# 1. Start a free signup (a *.agenticboxes.email subdomain inbox)
curl -s https://api.boxes.im/api/v1/signup/agentic \
  -H 'Content-Type: application/json' \
  -d '{"human_email":"owner@example.com",
       "domain_intent":{"mode":"subdomain"},
       "initial_credit_cents":0}'
# → { "intent_id": "int_…", "full_domain": "swift-fox-7.agenticboxes.email" }

# 2. Confirm — provisions the account and returns the API key
curl -s https://api.boxes.im/api/v1/signup/agentic/confirm \
  -H 'Content-Type: application/json' \
  -d '{"intent_id":"int_…"}'
# → { "primary_address": "agent@swift-fox-7.agenticboxes.email",
#     "api_key": "bxs_live_…", "account_status": "active" }
```

Store `api_key` immediately — it is returned exactly once. Every new account
starts with **250 messages of free credit**.

## Procedure

- **Base URL:** `https://api.boxes.im/api/v1`
- **Auth:** every call carries the header `Authorization: Bearer bxs_live_…`

### Send mail — `POST /messages/send`

```bash
curl -s https://api.boxes.im/api/v1/messages/send \
  -H 'Authorization: Bearer bxs_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com",
       "subject":"Hello",
       "text":"Sent by my agent."}'
```

Body: `to` (string or array, required), `subject`, `text`. Optional: `from`
(defaults to the account's primary address), `attachments`
(`[{filename, content_b64, content_type}]`), `idempotency_key`. The response
carries a `message_id` and a `billing` breakdown.

### Receive mail

- **Poll:** `GET /messages?include=body` — recent messages with full bodies
  inline. Also filterable by `direction` (values `received` or `sent`),
  `since`, `before`, `box`, `limit`.
- **One message:** `GET /messages/{id}`.
- **Push:** `PUT /account/callback-webhook` `{"url":"https://…"}` — inbound
  mail is POSTed to that URL the moment it arrives.

### Addresses (boxes)

A *box* is one email address. Create as many as the agent needs — no per-box fee.

- `POST /boxes` `{"address":"support"}` → `support@<your-domain>`
- `GET /boxes` — list them.

An address can only receive mail **after** its box is created.

### Credit — `POST /account/credit/topup`

Add prepaid credit when the balance runs low.

## Pitfalls

- The API key is shown **once**, at `confirm`. Capture it then or it is unrecoverable.
- An address receives mail only after `POST /boxes` creates its box.
- Sends fail with `402` / insufficient credit once the balance is spent — top up.
- The base URL ends at `/api/v1` — do not append `/v1` again.
- API keys carry scopes (`send` / `receive` / `admin`); use one with the scope the call needs.
- Pass `idempotency_key` on sends so a retried request never double-sends.

## Verification

- A successful send returns a `message_id` and a `billing` breakdown.
- `GET /messages` lists the account's sent and received mail.
- After `confirm`, `account_status` is `active` — the account is ready.