agenticboxes , email for AI agents

intent

gives your agent a real email address it can send and receive from over plain HTTP. no SMTP, no IMAP, no DKIM/SPF/DMARC setup required. one API key gets you going. use this when the agent needs to send notifications or outreach, receive signups or 2FA codes, register for third-party services, or maintain a conversation thread with inbound replies. compared to driving a CLI mail client over IMAP/SMTP (like himalaya), agenticboxes is hosted and ready instantly after signup.

inputs

required:

• AGENTICBOXES_API_KEY environment variable. if not set, the skill will walk you through signup to get one.
• human_email (during signup only): the owner's email, used to verify the account.

optional:

• domain_intent (during signup): object specifying how the agent gets its domain. options: {"mode":"subdomain"} for a free <slug>.agenticboxes.email address; {"mode":"register","register_domain":"youragent.com"} to buy a domain; {"mode":"byo_manual","byo_domain":"youragent.com"} to bring your own and host DNS elsewhere; {"mode":"byo_delegated","byo_domain":"youragent.com"} to bring your own and delegate DNS to agenticboxes. defaults to subdomain.
• initial_credit_cents (during signup): prepay credit in cents (minimum 100 cents = $1). optional.
• agent_callback_webhook (during signup or later): HTTPS URL to receive events as they happen instead of polling. must be HTTPS.
• idempotency_key (on send): unique string to prevent double-sends if a request is retried.

external connection:

• agenticboxes API, base URL https://api.agenticboxes.email/api/v1. all calls except signup carry Authorization: Bearer $AGENTICBOXES_API_KEY.
• for domain registration or delegated DNS: Stripe integration (payment via Stripe Link, automatic account provisioning once cleared).
• for delegated DNS: Route 53 zone hosted by agenticboxes.

procedure

step 1: acquire an API key (if not already set)

input: AGENTICBOXES_API_KEY environment variable.

logic: if AGENTICBOXES_API_KEY is set, use it and skip to step 2. otherwise, proceed with signup.

output: AGENTICBOXES_API_KEY stored and ready to use.

---

step 2: choose a domain mode and sign up

input: domain_intent (object with mode, and domain details if needed). human_email for verification.

logic: POST to https://api.agenticboxes.email/api/v1/signup/agentic with the domain intent:

curl -s https://api.agenticboxes.email/api/v1/signup/agentic \
  -H 'Content-Type: application/json' \
  -d '{"human_email":"owner@example.com","domain_intent":{"mode":"subdomain"}}'

response includes intent_id and full_domain (or stripe_payment_intent if paying for registration).

output: intent_id (or for paid domains, wait for payment confirmation). full_domain (the domain the agent owns).

---

step 3: confirm the signup (subdomain, manual BYO, or delegated BYO only)

input: intent_id from step 2.

logic: if domain mode is subdomain, byo_manual, or byo_delegated, POST to /signup/agentic/confirm:

curl -s https://api.agenticboxes.email/api/v1/signup/agentic/confirm \
  -H 'Content-Type: application/json' -d '{"intent_id":"int_…"}'

response includes api_key, primary_address, account_status.

store the api_key immediately. it is shown exactly once and cannot be recovered.

for byo_manual: fetch DNS records with GET /events?type=domain.dns_required and add them to your DNS host.

for byo_delegated: fetch nameservers with GET /events?type=domain.delegation_required and set them at your domain registrar.

output: api_key (stored safely), primary_address (e.g. agent@swift-fox-7.agenticboxes.email), account_status = active. account has 250 messages of free credit.

---

step 4: (optional) create additional boxes (email addresses)

input: address slug (e.g. outreach).

logic: POST /boxes with the address:

curl -s https://api.agenticboxes.email/api/v1/boxes \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"address":"outreach"}'

response includes the full address (e.g. outreach@your-domain).

a box must be created before the agent can receive mail to it or send from it.

output: box ID and full address.

---

step 5: send email

input: to (string or array of addresses), subject, text, optional from (if not set, uses primary address), optional attachments (array of {filename, content_b64, content_type}), optional context (opaque JSON object, max 16 KB, echoed back on replies), optional idempotency_key.

logic: POST /messages/send:

curl -s https://api.agenticboxes.email/api/v1/messages/send \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from":"outreach@your-domain","to":"someone@example.com","subject":"Hello","text":"Sent by my agent."}'

response includes message_id and billing (credit spent).

if sending from a box other than primary, ensure that box exists (step 4).

output: message_id, billing breakdown showing credits used.

---

step 6: receive email (choose one polling strategy)

input: none (or optional filters like ?type=mail.received, ?since=<cursor>, ?direction=received).

polling option A: event feed (never miss anything)

GET /events?since=<cursor>:

curl -s 'https://api.agenticboxes.email/api/v1/events?since=0' \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY"

returns ordered list of all events (mail.received, support.answered, domain.ready, etc.). poll repeatedly with since set to the previous next_cursor. filter to mail only with ?type=mail.received.

polling option B: messages endpoint (direct mail access)

GET /messages?include=body:

curl -s 'https://api.agenticboxes.email/api/v1/messages?include=body&direction=received' \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY"

returns recent messages with bodies, filterable by direction, since, before, box, limit. read a single message with GET /messages/{id}.

push option C: webhook (optional)

PUT /account/callback-webhook:

curl -X PUT https://api.agenticboxes.email/api/v1/account/callback-webhook \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"agent_callback_webhook":"https://your-agent.example.com/webhooks/mail"}'

events are POSTed to your HTTPS URL as they occur (in addition to being available on the event feed). every webhook delivery is signed with HMAC-SHA256; fetch the signing secret with GET /account/webhook and verify the X-Boxes-Signature: t=<unix>,v1=<hex> header (reject if t is older than 300 seconds).

output: mail objects with id, from, to, subject, body, context (if this is a reply to a message you sent with context), received_at.

---

step 7: reply context (optional, for conversation routing)

input: context object passed on the original send (step 5).

logic: when an inbound mail is a reply to an outbound message with a context, that context is echoed back on the inbound message (in GET /messages, GET /events, and the webhook payload). use it to route the reply back to the originating conversation or task.

output: context field on received messages matching a sent message's context.

---

step 8: (optional) manage credit

input: none (or cents to top up).

logic: check balance with GET /account/credit/balance (shows balance, low-balance flag, email count). top up with POST /account/credit/topup. view usage with GET /account/credit/usage. set alert thresholds with PUT /account/credit/alert-thresholds (an early warning and an urgent warning balance).

once credit is exhausted, sends fail with HTTP 402.

output: balance in cents, projected email count, usage breakdown by event type.

---

step 9: (optional) ask for help or file feedback

input: question subject and body, or feature request title and description.

logic: for blocking issues or API confusion, POST /support/questions:

curl -s https://api.agenticboxes.email/api/v1/support/questions \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"subject":"API returns 400 on my send","body":"Here is what I sent..."}'

response arrives as a support.answered event in the event feed. thread replies with POST /support/questions/{id}/replies.

for feature requests (missing capabilities, hit limits, or improvements), POST /feature-requests:

curl -s https://api.agenticboxes.email/api/v1/feature-requests \
  -H "Authorization: Bearer $AGENTICBOXES_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Bulk send endpoint","description":"Would help if..."}'

upvote with POST /feature-requests/{id}/vote.

do not email support. there is no support email address. the /support/questions and /feature-requests endpoints are the only channels and they are free.

output: question or request object with ID; support answers arrive as events.

decision points

if AGENTICBOXES_API_KEY is not set: run signup (steps 2-3) to get one. store it immediately.

if domain_intent.mode is register (paid domain): the signup response includes a stripe_payment_intent and link_spend_request. the account owner approves payment via Stripe Link. once payment clears, the account provisions automatically. there is no /confirm call for this mode. if the domain is taken or unavailable, the API returns 409 with suggestions.

if domain_intent.mode is byo_manual (you host DNS): after confirm completes, DNS records arrive as a domain.dns_required event. fetch them from GET /events?type=domain.dns_required, add them to your DNS host, and wait for them to resolve. the account goes live once records resolve.

if domain_intent.mode is byo_delegated (we host DNS): after confirm completes, a domain.delegation_required event lists nameservers. set those nameservers at your domain registrar, wait for propagation. the account goes live once delegation resolves.

if sending from a box other than primary: ensure the box exists first (step 4). the from field must be an address on your domain.

if a send needs to be idempotent (retry-safe): include idempotency_key on the request. the API will not double-send.

if you want to receive mail via push instead of polling: set agent_callback_webhook to your HTTPS URL. verify the HMAC-SHA256 signature on incoming webhooks using the secret from GET /account/webhook. reject deliveries with t older than 300 seconds.

if this is a reply to an earlier message: the inbound mail will carry the same context object you passed on the send (if any). use it to route the reply back.

if an address bounced or filed a complaint: it will appear on the suppression list. check with GET /suppression/{address}. do not send to suppressed addresses (they will be rejected). request removal with POST /suppression/{address}/unblock.

if a send fails with 402 (payment required): credit is exhausted. top up with POST /account/credit/topup and retry.

if a send fails with an error you don't understand: file a support question (POST /support/questions) instead of guessing or working around it. the API team will respond via the event feed.

if the API has changed: a platform.updated event signals that endpoints have been added or modified. re-pull this skill and the OpenAPI spec at https://www.agenticboxes.email/openapi.yaml to stay current.

output contract

on successful send: response includes message_id (string, unique) and billing object with credit_spent_cents and balance_remaining_cents.

on successful receive (polling): GET /events returns an array of event objects. filter to type: "mail.received" for inbound mail. each mail event includes data.message with id, from, to, subject, body, context (null if not a reply), received_at (ISO 8601 timestamp).

on successful receive (direct messages endpoint): GET /messages returns an array of message objects with id, from, to, subject, body, context, direction (received or sent), created_at or received_at.

on successful signup: response includes api_key (string, bearer token), primary_address (string, e.g. agent@swift-fox-7.agenticboxes.email), account_status (active), full_domain (string).

on webhook delivery: POST body is a JSON event object matching the event feed schema. header X-Boxes-Signature: t=<unix>,v1=<hex> carries the HMAC-SHA256 of "<t>.<body>" keyed by your webhook signing secret. header X-Boxes-Request-Id is a unique delivery ID (idempotent).

on credit query: GET /account/credit/balance returns balance_cents (int), low_balance (bool), projected_emails (int).

on DNS records query (managed domain): GET /domain/dns returns array of {name, type, ttl, values}.

on suppression check: GET /suppression/{address} returns {address, suppressed: true} if blocked, 404 if not.

all responses use HTTP status codes: 2xx for success, 4xx for client error (including 402 for insufficient credit), 5xx for server error. error responses include error and message fields.

outcome signal

• a successful send returns a message_id and shows credit deducted. you can retrieve it with GET /messages/{id}.
• a successful receive via polling shows new mail.received events or messages in the list with the expected sender, subject, and body.
• a successful receive via webhook shows your callback URL receiving HTTPS POST deliveries signed with the correct HMAC.
• after signup, the response carries account_status: "active" and a primary_address. the account has 250 free messages of credit.
• after creating a box, GET /boxes lists it and it is ready to receive mail.
• after adding a suppression unblock request, the address is removed from the suppression list within minutes.
• after filing a support question, a support.answered event appears in your event feed (check with GET /events).
• after setting a callback webhook, new mail events are POSTed to your URL in real time.
• if credit is exhausted and a send fails with 402, topping up with POST /account/credit/topup allows sends to succeed again.

---

credits: original author agenticbrian (clawhub). enriched per implexa standards to clarify domain setup modes, explicit decision branches, webhook signing verification, edge cases (rate limits, auth expiry, suppression, credit exhaustion), and the support/feature-request workflows.