Build verified-domain agent email workflows.

Getting started

LoftBox personal beta starts with one owner email. Signup creates the organization and emails a 6-digit verification token. Only after owner-email verification does LoftBox return the first API key, and that plaintext key is shown once. Verification also sends the owner a welcome email with the beta limits and future admin/billing signup path.

Personal beta accounts are limited to 100 outbound sends per day. Mailbox message retention defaults to 7 days. Enterprise onboarding, billing, org membership, and larger limits are roadmap items.

• POST /v1/auth/signupCreate a personal beta organization and send the owner-email verification token.
• POST /v1/auth/signup/verifyVerify the owner email, receive the initial API key once, and trigger the owner welcome notice.
• POST /v1/agentsCreate an agent identity with owner, purpose, and policy scope.
• POST /v1/domainsStart custom-domain onboarding for a domain you control.
• POST /v1/agents/{agent_id}/mailboxesCreate a LoftBox-managed beta mailbox or a verified custom-domain mailbox.
• POST /v1/messagesSend operational email from the agent mailbox.
• GET /v1/mailboxes/{id}/inboxPoll unacknowledged inbound messages when the agent has no webhook endpoint.

Base URL and machine-readable docs

The canonical public API endpoint is https://api.loftbox.net. The homepage keeps a /api/* proxy path for preview verification, but production integrations should use the dedicated API hostname.

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

Check the edge and schema before wiring an integration:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

The https://loftbox.net/api route strips the /api prefix and forwards to the same Fly API origin. Use it for Pages preview checks, not as the primary integration URL.

API auth

Start by registering the owner email for the personal beta organization. The owner receives a verification token by email; the verification call returns the initial API key once and sends the owner welcome notice.

export LOFTBOX_OWNER_EMAIL="owner@example.com"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

Use the returned server-side API key with the Authorization header. Never expose API keys in browsers, mobile clients, public logs, or analytics events.

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Store keys in server-side secret storage such as Fly secrets, environment variables managed by the deploy platform, or a dedicated secret manager. Do not paste real keys into issue comments, screenshots, analytics tools, or browser code.

Rotate keys when an operator leaves, a secret may have leaked, or an environment no longer needs API access.

One-line install and agent prompt

Agents can install the public LoftBox mail skills, then run the onboarding flow with only the owner email. The registration skill derives the organization label, stable external_id, agent slug, and mailbox local part from the current agent. After registration, the installed send and inbox-check skills use the issued API key and mailbox ID.

curl -fsSL https://loftbox.net/install.sh | sh

curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.

curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

Use update checks as a notification path only. Installing a new skill bundle changes agent behavior, so updates should run after operator approval.

Only ask for another value if the agent identity cannot be derived or a duplicate external ID belongs to a different agent.

Custom-domain onboarding

Every outbound domain must be verified before mailboxes can use it. The API returns the DNS records needed for ownership, inbound routing, sender alignment, and delivery verification.

1. Create the domain with POST /v1/domains.
2. Fetch required records with GET /v1/domains/{id}/dns.
3. Add the returned TXT, MX, DKIM, and return-path records at your DNS host.
4. Call POST /v1/domains/{id}/verify after DNS propagation.
5. Wait until inbound and outbound status are both verified before creating production mailboxes.

curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

For launch, personal beta uses LoftBox-managed delivery and LoftBox-managed inbound MX handling. Custom domains are enabled only after verification.

Agents and mailboxes

Agents hold the business purpose, ownership context, and stable external ID. Mailboxes attach an address and domain to that agent. Keep display names, owners, and policy scope clear enough for operator review.

• Use one mailbox per operational agent or workflow role.
• Use external_id for duplicate checks and idempotent agent setup.
• Use verified custom domains for production outbound mail.
• Disable or hold autonomous sends when the agent purpose is unclear.

curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

Omit domain_id for the LoftBox-managed personal beta domain. Register an agent webhook separately if the agent has an HTTPS endpoint.

Sending messages

Send operational or transactional messages through the API from a verified mailbox. LoftBox records delivery references, delivery state, rate-limit decisions, and operator approval outcomes.

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["recipient@example.com"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" }
}'

LoftBox is not a bulk marketing sender. Purchased lists, scraped recipients, and generic SMTP relay use are outside the MVP policy.

Inbound webhooks and polling

Replies are stored as inbound messages. Agents with an HTTPS endpoint can receive signed webhook events; agents without one should poll the mailbox inbox and acknowledge each processed message.

• message.inboundA new inbound message or reply was parsed, threaded, and made available to the configured webhook.
• message.deliveredDelivery was reported for the recipient.
• message.failedOutbound delivery failed permanently or exhausted retry handling.

curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

The webhook secret is returned once when the webhook is created. Store it immediately and verify every inbound signature before trusting event content.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

Only acknowledge after the agent has durably processed the message. Empty inbox polling should back off; active polling should use a moderate interval such as 30-60 seconds.

Delivery events

Delivery status is normalized across managed delivery callbacks and internal send state. Use event IDs and delivery references for support, not private recipient data.

• queued: accepted by LoftBox for delivery.
• sent: accepted for outbound delivery.
• delivered: delivery was reported for the recipient.
• failed: delivery failed permanently or exhausted retries.
• blocked: policy, rate limit, or report control blocked sending.

Rate limits and report controls

Outbound sending is limited by organization, agent, mailbox, recipient, and domain policy. Personal beta organizations are capped at 100 sends per day. High-risk messages can be held for approval before delivery is attempted.

Handle 429 responses by backing off. Do not retry indefinitely or bypass approval holds from another mailbox.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Managed delivery and safety setup

LoftBox operates managed outbound delivery for beta accounts. Public documentation should describe the customer-visible controls without exposing internal vendor names, credentials, or routing details.

• Business nature: API-managed operational email identities for verified-domain AI agents.
• Email types: transactional/system notifications, agent replies initiated by verified users, onboarding/test messages, and report/contact handling.
• Controls: verified domains only, explicit rate limits, delivery logs, suppression/complaint handling, and monitored report contact.
• Public pages: Privacy, Terms, and Anti-spam policy.

DNS propagation and delivery verification holds should be treated as setup state, not as proof that the API proxy or homepage docs are broken.