Skip to content
Faivelo Docs

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.

API access requires a Pro or Business plan.

Key kinds: account vs agent

Faivelo has two kinds of API key:

KindReachUse for
AccountThe whole account, within its scopesYour own scripts, integrations, admin tooling
AgentSandboxed: only mailboxes the key created or was explicitly grantedCredentials 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

ScopeGrants
mail:readList, read, and search messages; folders; contacts
mail:sendSend mail (counts against your plan’s send allowance)
mail:writeFlag, move, mark spam, delete messages
mailboxes:readList mailboxes
mailboxes:writeCreate and update mailboxes
dns:read / dns:writeQuery and edit a domain’s live DNS records
domains:read / domains:writeManage domains (account keys only)
aliases:read / aliases:writeManage aliases (account keys only)

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

LimitValue
Requests per key120 per minute
Mailbox creations per key10 per rolling 24 hours
SendingCounts against your plan’s monthly allowance

These caps keep a misbehaving agent contained without getting in the way of normal traffic.

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:

Terminal window
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/mail/send to send, and the message endpoints to poll for and read replies (great for extracting verification codes).

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