API

Everything the app does to an audience, a template or a campaign is reachable over HTTP. A script — or an agent — works on the same data as the interface, with the same rules, without a browser session. This page is the map: authentication, the shape of every answer, and every endpoint with the page that details it. Each endpoint has its own page — one call, its parameters, its answers and what it refuses.

Every endpoint

Sequences
POSTCreate a sequence/api/v1/sequencesGETList sequences/api/v1/sequencesGETGet a sequence/api/v1/sequences/{sequenceId}PATCHRename, activate or pause/api/v1/sequences/{sequenceId}DELETEDelete a sequence/api/v1/sequences/{sequenceId}GETWho is walking it/api/v1/sequences/{sequenceId}/enrollmentsGETList versions/api/v1/sequences/{sequenceId}/versionsPOSTOpen a draft version/api/v1/sequences/{sequenceId}/versionsPATCHChange a draft's trigger/api/v1/sequences/{sequenceId}/versions/{versionId}POSTPublish a version/api/v1/sequences/{sequenceId}/versions/{versionId}/publishPOSTRoll back to a version/api/v1/sequences/{sequenceId}/versions/{versionId}/rollbackDELETEDiscard a draft/api/v1/sequences/{sequenceId}/versions/{versionId}POSTAdd a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodesGETList steps/api/v1/sequences/{sequenceId}/versions/{versionId}/nodesPATCHEdit a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}DELETERemove a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}POSTMove a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}/moveGETList wires/api/v1/sequences/{sequenceId}/versions/{versionId}/edgesPOSTWire two steps/api/v1/sequences/{sequenceId}/versions/{versionId}/edgesDELETEUnwire two steps/api/v1/sequences/{sequenceId}/versions/{versionId}/edges/{edgeId}

Authentication

Every /api/v1 request carries an API key in the x-api-key header. A key is created from the app and belongs to one organization: that organization is the entire scope of the key.
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags"

The key acts as the person who created it

A key is not a second identity with its own powers. It carries the rights of the member who created it, in the organization it was created for. A key made by an admin can write; a key made by a member can read. Nothing is granted through the API that the same person could not do in the interface.
A key stops working when its owner leaves the organization. No orphan access survives a departure: the key answers 401 from that moment, exactly as if it had been revoked. Revoking the key of someone who left is therefore a cleanup, not a security fix.
Two rules decide every call, and both have to pass:
QuestionDecided byAnswer when it fails
Is the caller still a member, with which role?The key's owner and their role401 / 403
Does the resource belong to the key's organization?The key's organization404

Who can do what

OperationMinimum role in the organization
Reading anything, and POST /api/v1/rendermember
Creating, updating, deleting, tagging, sendingadmin
POST /api/v1/render is the exception among the write verbs because it writes nothing: it renders and returns, with no side effect.

Response envelope

CaseBody
Success{"success": true, "data": …}
Paginated list{"success": true, "data": [...], "pagination": {"total", "page", "limit", "totalPages"}}
Error{"error": "…"}
Validation error{"error": "…", "details": [ … Zod issues … ]}
StatusWhen
200Read or mutation done
201Resource created
202Send accepted, happening in the background — nothing is finished yet
400Invalid parameters or body — details lists the offending fields
401Missing or invalid key, or a key whose owner left the organization
403The caller is a legitimate member, but their role is too low
404Unknown resource, or a resource of another organization
409State conflict — a tag name already taken, a campaign already sent
429Rate limit of the key exceeded
500Unexpected server error
A resource of another organization answers 404, never 403. A 403 would confirm that the id exists. Same response for an unknown id and for an id you are not allowed to read — you cannot tell them apart, and that is the point. The 403 is reserved for the other question: you are in the right organization, your role is too low.

Rate limit

The limit is carried by the key, not by the IP. A key over its limit answers 429 on every endpoint. Back off and retry: nothing was done.

Where to start

Start with Discovery: two calls turn a bare key into a context — the organization it opens, and the listId every audience endpoint asks for. Then read the audience — a campaign without a list to send it to goes nowhere — and compose with templates and rendering. The whole path from an empty organization to a sent newsletter is walked end to end at the bottom of Campaigns.