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.

The REST API is included on every paid plan (and during the free trial); the hosted MCP server is included from Growth. Sending pace scales with the plan — see Rate limits.

Key kinds: account vs agent

Faivelo has two kinds of API key:

Kind	Reach	Use for
Account	The whole account, within its scopes	Your own scripts, integrations, admin tooling
Agent	Sandboxed: only mailboxes the key created or was explicitly granted	Credentials you hand to an AI agent

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 → API Keys 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

Scope	Grants
mail:read	List, read, and search messages; folders; contacts
mail:send	Send mail (counts against your plan’s send allowance)
mail:write	Flag, move, mark spam, delete messages
mailboxes:read	List mailboxes
mailboxes:write	Create and update mailboxes
dns:read / dns:write	Query and edit a domain’s live DNS records
domains:read / domains:write	Manage domains (account keys only)
aliases:read / aliases:write	Manage aliases (account keys only)
drive:read	List files and folders in your Faivelo Drive and get file download URLs

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

Limit	Value
Requests per key	120 per minute
Mailbox creations per key	10 per rolling 24 hours
Sending	Counts against your plan’s monthly allowance
Sending rate (recipients/min)	Starter & trial: 10 · Growth: 30 · Pro: 60 · Business: 120
Transactional emails per month	Trial: 100 · Starter: 500 · Growth: 10,000 · Pro: 100,000 · Business: 250,000
Campaign sends per month (separate budget)	Growth: 3,000 · Pro: 25,000 · Business: 100,000

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).

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_..."

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_...

Caution

A key in a URL can end up in logs and config files. Prefer the Authorization header whenever your client supports it, and rotate any key you suspect has leaked.

The MCP toolset covers the full mail surface: discovery (list_mailboxes, list_domains, get_account_summary), reading (list_messages, read_message, get_thread, search_messages, search_all_mailboxes, list_folders, get_contacts, get_attachment), sending (send_message with attachment support), housekeeping (flag_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 — 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.