Create a campaign

POST /api/v1/campaigns Creates a campaign in draft. Answers 201.

The content is copied from the template, it is not part of the body. Edit the template, then create the campaign — a campaign never drifts from what you rendered. tagId takes an id, not a name: resolve it with GET /api/v1/tags.

sendingIdentityId takes an id from your address book — list them with GET /api/v1/settings/identities, where each entry carries its id, its senderEmail and whether it is the default. An address belonging to another organization is refused with 403.Leaving it out is not the same as pinning the default. A campaign with no sendingIdentityId follows the default as it is at send time: promote another address and that campaign follows. A campaign that names an address keeps it, whatever the default becomes. See Settings & domains for the address book itself.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Request body

Field	Type	Required	Description
`name`	string	yes	1 to 100 characters, internal name
`subject`	string	yes	1 to 200 characters, the subject recipients see
`templateId`	string	yes	Template of your organization
`listId`	string	yes	List to send to
`tagId`	string	no	Narrows the list to the contacts carrying this tag
`sendingIdentityId`	string	no	The address that signs this campaign. Omitted or `null`: the organization's default

Example

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "August newsletter",
    "subject": "What shipped in August",
    "templateId": "'$TEMPLATE_ID'",
    "listId": "'$LIST_ID'",
    "sendingIdentityId": "'$IDENTITY_ID'"
  }' \
  "https://www.agentsmail.io/api/v1/campaigns"

Response

201 Created — the created resource.
401 Unauthorized — missing or invalid key, or its owner left the organization.
403 Forbidden — the key's owner is a member of the organization, not an admin.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.id`	string	Unique identifier for the campaign
`data.name`	string	Its internal name
`data.subject`	string	The subject recipients see
`data.status`	string	`draft`, `scheduled`, `sending`, `sent`, `failed`
`data.listId`	string	The list it targets
`data.tagId`	string	null
`data.segmentId`	string	null
`data.scheduledAt`	string	null
`data.sentAt`	string	null
`data.createdAt`	string	ISO creation date
`data.updatedAt`	string	ISO date of the last change

Example response

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "name": "Newsletter",
    "subject": "August news",
    "status": "subscribed",
    "listId": "0b7c51e8",
    "tagId": "7c2ef4b1",
    "segmentId": "3f81aa2c",
    "scheduledAt": "2026-08-23T10:22:05.000Z",
    "sentAt": "2026-08-23T10:22:05.000Z",
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}