Docs/ Platform & apps

API, MCP & webhooks

Connect AI agents over MCP, call the REST API with scoped keys, and receive signed webhooks.

Settings > Developer is where you connect AI agents such as Claude or ChatGPT to your inbox, create API keys for your own integrations, and set up webhooks. What your plan includes is shown on the page.

Connect an AI agent (MCP)

AI Emaily runs a Model Context Protocol server at https://mcp.aiemaily.com. Add it as a connector in your AI client: it opens AI Emaily's sign-in, where you approve the scopes you want to grant. Settings > Developer has step-by-step instructions for Claude, ChatGPT, Claude Code and Cursor.

Connected agents lists every connected app with when you connected it. Revoke access takes effect immediately.

Sending through MCP always goes draft first, then an explicit send. The full tool list and setup guides are on the MCP page.

API keys

  1. 1

    Create a key

    In Settings > Developer, select Create key, give it a name, and tick only the scopes it needs. Scopes cannot be expanded later.

  2. 2

    Copy it once

    The full key is shown only once. Store it in a secrets manager; if you lose it, create a new key.

  3. 3

    Call the API

    Send the key as a bearer token to https://api.aiemaily.com/v1. The API reference documents every endpoint.

  4. 4

    Revoke when done

    Select Revoke key. Revoked keys stop working at once.

Scope groupScopes
Mailmail:read, mail:write, mail:send, drafts:read, drafts:write
Search & contactssearch:read, contacts:read, contacts:write
AI & agentsai:invoke, agent:read, brief:read
Data & contextcontext:read, context:write, calendar:read, calendar:write
Platformwebhooks:manage, usage:read

Rate limits

Requests are limited to 120 per minute per API key and 300 per minute per account. Your plan also sets a daily number of API requests and API sends, shown under Rate limits in Settings > Developer. Going over a limit returns HTTP 429 with a Retry-After header.

Reads and non-AI writes don't use credits. AI actions through the API use credits like the same actions in the app.

Webhooks

Webhooks send an HTTPS POST to your endpoint when something happens. Select Add endpoint, enter the HTTPS URL, and pick events: message.received, thread.updated, send.completed, send.failed, draft.created, agent.action and brief.ready.

Each delivery is signed with HMAC-SHA256 in the X-Aiemaily-Signature header. The signing secret is shown once when you add the endpoint. Rotate secret gives you a new one, and the old secret keeps signing for 24 hours so you can switch without missing deliveries.

Each endpoint has Test, Edit, Disable and Delete, and shows recent deliveries with attempts. An endpoint that fails for three days straight is disabled automatically; fix it and enable it again. Your plan sets how many endpoints you can add.

Frequently asked

Ready to try it?

Start Free Trial