Flomailr/Docs

OpenAPI Spec

Flomailr publishes its REST API as an OpenAPI 3.1 document. An AI coding agent such as Claude Code, Cursor or Codex can read it and write correct calls without guessing, and any tool that reads OpenAPI 3.1 can import it.

https://flomailr.com/openapi.json

The file is public and needs no API key. It describes every route under /api/v1: paths, query parameters, request bodies with their limits and allowed values, response shapes and error codes. It is the same API described on the other pages in this section. A test compares the spec to the route files, so a route cannot ship without being listed.

Use it with a coding agent

  1. Point the agent at the URL. For example: "Integrate with Flomailr using the API described at https://flomailr.com/openapi.json."
  2. Give it an API key. A workspace admin creates one under Settings > API keys (see API Keys). The key is shown once. Put it in an environment variable such as FLOMAILR_API_KEY and have the agent read it from there. Do not paste it into a prompt or commit it.
  3. Ask for what you need: a typed client, a sync job, a signup handler. The agent sends the key as Authorization: Bearer <key>.

To look at the spec yourself:

curl https://flomailr.com/openapi.json

The response is cached for an hour.

What the agent should know first

The top of the spec (info.description) covers these, and each operation repeats what matters for it.

  • Consent. POST /contacts creates a new address as SUBSCRIBED unless you send status: "PENDING", which is you saying the person agreed to marketing email. An opted-out contact is not brought back by status alone; that needs consent: "explicit". POST /events always creates unknown addresses as PENDING. See Contacts.
  • Sends reach real people. POST /campaigns/{id}/send and POST /send email real people and cannot be undone. Have the agent create a draft, show it to you, and ask before it sends.
  • Sending limits. Campaign sends skip suppressed addresses and blocked domains, and are refused when they would pass the daily cap or the monthly plan limit or start inside quiet hours. Transactional sends skip bounced, complained and manually blocked addresses and count toward the monthly limit, but quiet hours and the daily cap do not apply.
  • Retries. Send an Idempotency-Key header on POST /send so a retry cannot send twice. Send an externalId on POST /events for the same reason.
  • Pagination. List routes take limit (up to 100) and after. Follow pagination.nextCursor until it is null.
  • Errors. Every error is { "error": { "code", "message" } }. Read message: for example, a campaign send that is refused for the monthly limit can arrive as 422 rather than 402.

What is in the spec

Contacts, lists, campaigns (create, edit, schedule, send), signup forms, automations and their enrollments, events, transactional send, and API keys. Fields the API does not return are not in the spec: a campaign's HTML body and an automation's flow can be written but never read back.

What is not in the spec

  • The hosted MCP connector. If your AI app supports connectors, connect it instead of using REST. See Connect Your AI.
  • The public form submit endpoint (POST /api/forms/{id}/submit). The spec only gives you each form's embedUrl. See Forms.
  • A request rate limit. The routes apply none of their own, so there is nothing to plan around besides the sending limits above.