Introduction

Mailgentic is email infrastructure for software that sends and receives mail on its own: AI agents, automations and multi-tenant platforms. One HTTPS API (plus SMTP, IMAP and MCP) gives you:

Sending — a multi-tenant relay with quotas, rate limits, DKIM, suppression lists, idempotent submission and signed webhooks.
Inboxes — a real address for every agent: receive, read, search, file, reply and forward over the API, with threads, folders, drafts and scheduled send.
Safety — Agent Shield screens inbound mail (SPF/DKIM/DMARC, spam, prompt-injection and phishing heuristics) and polices outbound mail (DLP, rate caps, recipient allowlists, human approvals). The Guardian watches sending behaviour across tenants and benches a misbehaving one within a minute, without dropping anything.
Receipts — every control action lands in an append-only, hash-chained audit log.

Base URL and versioning

https://api.mailgentic.ai

All REST endpoints live under /v1. Inbox endpoints are not a separate namespace; they share the same host and version and are simply scoped to the tenant or inbox your credential is attached to.

Protocol	Endpoint	Use it for
REST	`https://api.mailgentic.ai/v1`	Everything. Described by the OpenAPI 3.0 spec and the interactive reference.
SMTP submission	`smtp.mailgentic.ai` ports 465 (TLS) / 587 (STARTTLS)	Legacy apps, mail libraries, sending from an inbox with any client
IMAP	`imap.mailgentic.ai` ports 993 (TLS) / 143 (STARTTLS)	Reading an inbox from Thunderbird, mutt, `imaplib`, etc.
MCP	`POST https://api.mailgentic.ai/mcp`	Letting an MCP-capable agent use an inbox as a tool set
Webhooks, SSE, WebSocket	You register / subscribe	Push delivery of events

Core concepts

Term	Meaning
Account	You — the platform or team that signed up. Owns tenants, keys, webhooks, billing and the audit log.
Tenant	A customer, workspace or agent fleet inside your account. Quotas, rates, domains, suppressions, pauses and reputation are tracked per tenant, so one tenant’s problem never touches another.
Domain	A sending (and optionally receiving) domain registered to a tenant and verified via DNS.
Inbox	An address on an inbound-enabled domain, owned by a tenant, with its own threads, folders, policy and optional inbox-scoped keys.
API key	A bearer credential with scopes. Can be account-wide, bound to one tenant, or pinned to one inbox.
Message	An outbound submission (relay) or an inbound/outbound item in an inbox.
Event	An immutable record (`delivered`, `bounced`, `message.received`, `approval.required`, …) delivered by webhook, SSE or WebSocket.

A first request

No account yet? Sign up — email and password, no card — and the console hands you a mailbox and a key in under a minute. Then:

curl https://api.mailgentic.ai/v1/account \
  -H "Authorization: Bearer $MAILGENTIC_KEY"

If that returns your account, you are ready for the sending quickstart or the inbox quickstart.

Conventions used in these docs

Requests and responses are JSON; send Content-Type: application/json.
Errors always use { "error": { "code": "...", "message": "..." } }. See Errors and limits.
IDs are opaque UUIDs. A 404 also covers resources outside your tenant or inbox scope; do not use it to distinguish “missing” from “forbidden”.
Lists return newest first with limit (default 50, max 200) and a cursor parameter. See each page for the cursor field.
Mailgentic is a CYFOX product. A few wire-level identifiers carry the company name and are stable: API keys are prefixed cfx_, webhook headers are X-Cyfox-*, and the WebSocket subprotocol is cyfox.<token>.

Client libraries

There is no SDK to install. The API is a plain OpenAPI 3.0 service, so every example in these docs is curl, and you can generate a typed client for any language in one command:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.mailgentic.ai/openapi.yaml -g typescript-fetch -o ./mailgentic

Agents don’t need a client at all: point them at the MCP server. Official TypeScript and Python packages are on the roadmap and will be announced here when they ship.