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.topicId works the same way, resolved with GET /api/v1/topics. Content carrying {{topicOptOutUrl}} on a campaign with no topic makes the send refused — the link would be dead. See Topics.

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
`previewText`	string \| null	no	Preview text, up to 200 characters after trimming. `null` clears it; omitted on PATCH keeps it. Rendered at `{{previewText}}` or `{{preheader}}`
`preheader`	string \| null	no	Compatible alias of `previewText`. When both are supplied they must match after trimming, otherwise `400`
`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
`topicId`	string	no	Editorial topic this campaign carries. Required for `{{topicOptOutUrl}}` to render
`sendingIdentityId`	string	no	The address that signs this campaign. Omitted or `null`: the organization's default

json

{
  "name": "August newsletter",
  "subject": "What shipped in August",
  "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.",
  "templateId": "2b2b2b2b-3333-4ddd-8eee-ffff00001111",
  "listId": "9f8e7d6c-1111-4bbb-8ccc-ddddeeeeffff"
}

Use one alias. If both are present, they must match after trimming, including null; conflicting values return 400. An empty string also removes the preview text.

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",
    "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.",
    "templateId": "'$TEMPLATE_ID'",
    "listId": "'$LIST_ID'",
    "sendingIdentityId": "'$IDENTITY_ID'"
  }' \
  "https://www.agentsmail.io/api/v1/campaigns"

Response

400 Bad Request — invalid fields, preview text over 200 characters, or conflicting aliases.
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.previewText`	string \| null	Saved preview text; equal to `data.preheader`
`data.preheader`	string \| null	The preview text shown after the subject, `null` when there is none
`data.status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`data.listId`	string	The list it targets
`data.tagId`	string	null
`data.topicId`	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