Get a campaign

GET /api/v1/campaigns/{campaignId} Returns a campaign with its live recipient count and send progress. recipientCount is computed from the current target; it is not a stored estimate.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Allowed

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

Path parameters

Parameter	Type	Description
`campaignId`	string	Unique identifier of a campaign

Example

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID"

Response

200 OK — the campaign and its current send information.
401 Unauthorized — missing or invalid key, or its owner left the organization.
404 Not Found — no such campaign, or it belongs to another organization.
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	Internal campaign name
`data.subject`	string	Subject shown to recipients
`data.content`	string	HTML content sent to recipients
`data.status`	string	`draft`, `scheduled`, `sending`, `sent`, `failed`, or `deleted`
`data.templateId`	string \| null	Source template, when the campaign was created from one
`data.listId`	string	List targeted by the campaign
`data.tagId`	string \| null	Optional tag narrowing the list
`data.sendingIdentityId`	string \| null	Selected sender identity; `null` uses the default identity
`data.scheduledAt`	string \| null	Scheduled departure time in ISO 8601 format
`data.sentAt`	string \| null	Completion time in ISO 8601 format
`data.createdAt`	string	Creation time in ISO 8601 format
`data.updatedAt`	string	Last campaign change in ISO 8601 format
`data.recipientCount`	number	Subscribed contacts matched by the target right now
`data.progress.total`	number	Send records created for the campaign
`data.progress.sent`	number	Messages confirmed as sent
`data.progress.failed`	number	Messages that ended in failure
`data.progress.pending`	number	Messages not yet attempted
`data.progress.sending`	number	Messages currently reserved for processing
`data.progress.staleSending`	number	Reserved messages whose processing window has expired
`data.progress.lastActivityAt`	string \| null	Most recent real send activity: `sentAt` for a dispatched message, terminal transition time for a failed or skipped message
`data.progress.chunkSize`	number	Number of messages assigned to one processing batch
`data.sendingEnabled`	boolean	Whether campaign sending is currently enabled across AgentsMail

Example response

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "name": "Newsletter",
    "subject": "August news",
    "content": "<p>Hello {{firstName}}</p>",
    "status": "sending",
    "templateId": null,
    "listId": "0b7c51e8-5df6-4e87-9fc2-d272dca63214",
    "tagId": "7c2ef4b1-94da-46df-b2c4-b390282adf64",
    "sendingIdentityId": null,
    "scheduledAt": "2026-08-23T10:22:05.000Z",
    "sentAt": null,
    "createdAt": "2026-08-23T10:20:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z",
    "recipientCount": 1240,
    "progress": {
      "total": 1240,
      "sent": 1200,
      "failed": 2,
      "pending": 35,
      "sending": 3,
      "staleSending": 1,
      "lastActivityAt": "2026-08-23T10:31:44.000Z",
      "chunkSize": 14
    },
    "sendingEnabled": true
  }
}

Notes

staleSending is included in sending; do not add the two values together.
Opens and clicks do not refresh lastActivityAt.
A non-zero staleSending value does not prove that a message was not accepted. Do not resend it automatically.
recipientCount excludes unsubscribed, bounced, and complained contacts.