AI agents & API keys

AI agents need real email addresses — to sign up for services, receive verification codes, and talk to humans. Faivelo lets an agent spin up its own mailbox on your domain and drive it over a simple REST API or the hosted MCP server, with credentials that can't touch the rest of your account.

Agent inboxes are their own product, Faivelo Agents, with its own plan next to (or without) an email hosting plan. Every Agents plan, Free included, comes with the REST API, the hosted MCP server and message webhooks. An agent with no account at all can start on a free address: see Start without an account.

Plans

Past the monthly emails, receiving keeps working and sending pauses after a 10% grace, with 402 and code AGENT_EMAIL_LIMIT until the 1st (UTC) or an upgrade. One inbox past the plan's count answers 402 with AGENT_INBOX_LIMIT. Drafts, labels and threads work on agent inboxes; on a person's mailbox they answer 403 with agent_inbox_only. Change plans under Billing.

Start without an account

An agent in a terminal has no browser, no card and no inbox of its own to confirm. One call gives it a free address, an inbox on it and a key bound to that inbox:

curl -X POST https://faivelo.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-bot"}'

Or, with Node installed, the same thing from the CLI (it also writes FAIVELO_API_KEY and FAIVELO_INBOX to ./.env when run inside a project):

npx faivelo inbox acme-bot --json

The answer:

{
  "address": "agent@acme-bot.fvlmail.com",
  "api_key": "fvl_live_...",
  "claim_url": "https://faivelo.com/claim/...",
  "expires_at": "2026-10-11T12:00:00.000Z",
  "base_url": "https://faivelo.com/api/v1/mailboxes/agent@acme-bot.fvlmail.com",
  "mcp_url": "https://faivelo.com/api/mcp"
}

name is optional (a random agent-xxxxx is picked otherwise) and inbox sets the local part (default agent). The key is shown once.

Until a person claims it

The account has nobody behind it yet, so it is receive-first: the inbox receives, the key reads, searches, fetches attachments and connects over MCP, which is enough to sign up for a service, read the code and hold a conversation. Sending is limited to replies: up to 5 a day, only to addresses that wrote to the inbox first. Any other send answers 403 with code CLAIM_REQUIRED. Every response carries X-Faivelo-Claim: required and X-Faivelo-Claim-Expires; after 7 days unclaimed the address and the account are removed.

Claiming

claim_url is for the person the agent works for. They open it, sign in or create a free account, and the address, its inboxes, keys and webhooks move into their account: the keys keep working, sending opens up to the free plan's 50 a day, the expiry goes away and the Inboxes console shows what the agent set up. The link is single-use; POST /api/v1/account/claim with the inbox key mints a fresh one.

Signups are budgeted per address, per network and platform-wide; a refused one answers 429 or 503 with a plain message.

Key kinds: account vs agent

Faivelo has two kinds of API key:

Agent keys are the safe default for autonomous software. An agent key can create mailboxes and then operate them — but it can never read your other inboxes, add or remove domains or aliases, touch billing, or mint new keys. Revoke it at any time and access stops instantly.

Create a key

1. Go to Settings → Developers in your dashboard.
2. Choose the kind (agent for anything autonomous) and the scopes it needs.
3. Copy the key — it starts with fvl_live_ and is shown exactly once.

Scopes

Agent keys can hold at most the mailbox, DNS and mail scopes — domain and alias management is deliberately off-limits so an agent credential can never reshape your account. DNS is allowed because agents pointing records at their own services is a core use case; records that email delivery depends on (MX, SPF, DKIM, DMARC, …) are flagged mailCritical and any edit or delete of them is refused unless the request repeats with an explicit force: true.

Rate limits

Sending limits are counted per account (not per key) across the REST API, MCP, and transactional sending together. Exceeding one returns 429 with a plain-English message and how long to wait; a request with more recipients than your per-minute rate is rejected outright — split the list.

Like every email provider, new accounts also warm up: sending volume starts modest and rises automatically as you send cleanly, the same way a fresh domain builds reputation. You'll rarely notice it — and if your sending has outgrown the automatic ramp, request a higher limit in Settings → Sending limits; it's usually approved the same day.

REST API

The full REST surface — domains, mailboxes, aliases, sending, folders, messages, search, attachments — is documented in the API reference. Authenticate with a Bearer header:

curl https://faivelo.com/api/v1/mailboxes \
  -H "Authorization: Bearer fvl_live_..."

The typical agent loop is three calls: POST /api/v1/mailboxes to provision an address like my-agent@yourdomain.com, POST /api/v1/mailboxes/{address}/send to send, and the message endpoints to poll for and read replies (great for extracting verification codes).

Give the mailbox a displayName when you create it. It is the name recipients see; without one (and no domain default) they see only the bare address, and the response carries a hint. Rename it later with PATCH on the mailbox or the update_mailbox MCP tool. For a one-off name, pass fromName, or write from as "Support Bot <bot@yourdomain.com>".

For application mail — receipts, password resets, alerts — see Transactional email: POST /api/v1/emails sends from any address on a verified domain with no mailbox required, supports designed templates, and can push delivery events to your server via webhooks.

Reading Drive files

With the drive:read scope a key can browse the account's Faivelo Drive and pull file contents — useful for agents and integrations that need to ingest a stored spreadsheet or document. List a folder (omit parentId for the root), then exchange a file id for a short-lived download URL:

# List the Drive root
curl "https://faivelo.com/api/v1/drive" \
  -H "Authorization: Bearer fvl_live_..."

# Get a presigned URL for a file, then download it
curl "https://faivelo.com/api/v1/drive/<fileId>/download-url" \
  -H "Authorization: Bearer fvl_live_..."

Send one email to many recipients

An agent that has to tell twelve people the same thing should not spend twelve turns on it. POST /api/v1/mailboxes/{address}/send-batch (the send_batch MCP tool) takes one subject and body and a list of recipients, and Faivelo does the rest server-side: it queues the batch, sends it at your plan's pace, and tracks every recipient. {{field}} tokens in the subject, text or html are filled from each recipient's fields; a field a recipient lacks renders empty (and is named in missingFields, so you can see it). The response comes back at once with a batch id and every recipient as queued.

curl https://faivelo.com/api/v1/mailboxes/updates@$DOMAIN/send-batch \
  -H "Authorization: Bearer $FAIVELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Hi {{first_name}}, the beta opens Monday",
    "text": "Hi {{first_name}}, your invite code is {{code}}.",
    "recipients": [
      { "email": "ada@example.com", "fields": { "first_name": "Ada", "code": "ADA-1" } },
      { "email": "linus@example.com", "fields": { "first_name": "Linus", "code": "LIN-2" } }
    ],
    "idempotencyKey": "beta-invites-2026-10"
  }'

GET /api/v1/mailboxes/{address}/send-batch/{id} (get_batch_status over MCP) reports each recipient as queued, sent, delivered, bounced, complained or failed with the reason. Delivery states arrive from the mail system a little after each send; the email.delivered, email.bounced and email.complained webhooks fire per recipient and carry batch_id, so you need not poll.

The rules, written for an agent to rely on:

• The whole batch is accepted or refused. More recipients than your per-call cap answers 422 with code batch_too_large; more than what is left of the monthly send allowance answers 403 with send_limit_reached. In both cases nothing was queued and the error names the cap, so split the list or send fewer. GET /api/v1/usage reports the cap as batch.recipientsPerCall and the allowance as sends.
• Every recipient counts as one send against the same monthly allowance a single send draws on. Campaigns are a separate product with their own quota: use them for newsletters to opted-in lists, with unsubscribe links and open tracking. Bulk send is for an agent's own correspondence: notices, invitations, follow-ups.
• The per-call cap follows the plan, the larger of your mail plan's and your Agents plan's: Free agents tier 20, Growth, Pro and Business 100, Developer 200, Scale 1,000. Starter alone has no bulk send (and no MCP).
• idempotencyKey is required. Derive it from the event ("invoice-run-2026-10"), not a timestamp. A repeat with the same key returns the original batch with replayed: true; the same key with a different request is refused.
• Pacing is handled for you. A batch sends at the plan's recipients-per-minute rate (see the table above) and waits out any limit it meets; a 100-recipient batch on Growth takes about two minutes. Each recipient still passes the mailbox's send lists and, on an unclaimed or sandboxed account, the same recipient rules as a single send: those are checked up front, before anything is queued.

The SDKs wrap it as faivelo.mailboxes.sendBatch(address, {...}) / getBatch(address, id) (Node) and faivelo.mailboxes.send_batch(address, ...) / get_batch(address, id) (Python).

MCP for headless agents

The same hosted MCP server that powers the Claude connector accepts raw API keys, so headless agents skip OAuth entirely. Point any Streamable-HTTP MCP client at the endpoint with a Bearer header:

{
  "mcpServers": {
    "faivelo": {
      "url": "https://faivelo.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fvl_live_..."
      }
    }
  }
}

If your client can't set custom headers, embed the key in the URL instead:

https://faivelo.com/api/mcp/fvl_live_...

The MCP toolset covers the full mail surface: discovery (list_mailboxes, list_domains, get_account_summary, get_setup_summary), reading (list_messages, read_message, get_thread, search_messages, search_all_mailboxes, list_folders, get_contacts, get_attachment), sending (send_message with attachments and an optional sendAt; send_batch and get_batch_status for one templated email to many recipients in a single call), drafts and scheduled sends (create_draft, update_draft, send_draft, list_scheduled, cancel_scheduled), housekeeping (flag_message, label_message, mark_all_read, move_message, restore_message, mark_spam, delete_message, empty_trash), aliases (list_aliases, create_alias, delete_alias), DNS (list_dns_records, create_dns_record, update_dns_record, delete_dns_record — mail-critical records need force: true), deliverability (get_delivery_status), Drive (drive_list_files, drive_download_file — with the drive:read scope), and create_mailbox and update_mailbox (set or clear the name a mailbox sends as) — all enforcing the same scoping, creation caps, and rate limits as the key itself. Agent keys see only the mailboxes they created or were granted, and their aliases may only route to those mailboxes.

Next steps

• API reference — every endpoint, schema, and example.
• Connect Claude — the no-key OAuth flow for claude.ai and Claude Code.