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`	object	Campaign object.
`data.campaignUrl`	string \| null	Campaign page.
`data.campaignEditorUrl`	string \| null	Content editor for an editable draft.
`data.campaignStatsUrl`	string \| null	Statistics for a sent campaign.
`data.campaignPreviewUrl`	string \| null	Internal preview of a sent campaign.
`data.publicCampaignUrl`	string \| null	Shareable archive for a sent campaign with public archives enabled.
`data.id`	string	Unique identifier for the campaign
`data.name`	string	Internal campaign name
`data.subject`	string	Subject shown to recipients
`data.previewText`	string \| null	Saved preview text; equal to `data.preheader`
`data.preheader`	string \| null	Preview text shown after the subject; `null` when there is none
`data.content`	string	HTML content sent to recipients
`data.status`	string	`draft`, `scheduled`, `paused`, `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.topicId`	string \| null	Editorial topic this campaign carries, if any
`data.sendingIdentityId`	string \| null	Selected sender identity; `null` uses the default identity
`data.scheduledAt`	string \| null	Scheduled departure time in ISO 8601 format; retained while `paused`
`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

All five links are absolute URLs in the organization’s language (en by default). Unavailable links are null; all are null when the organization has no URL slug. Internal links require sign-in and appropriate organization access; only publicCampaignUrl is public. API and MCP agents should display relevant non-null URLs as clickable Markdown links, for example [Open campaign](campaignUrl) using the returned URL. Creating or reading a campaign does not publish it.

Example response

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "name": "Newsletter",
    "subject": "August news",
    "previewText": "Three new things this month",
    "preheader": "Three new things this month",
    "content": "<p>Hello {{firstName}}</p>",
    "status": "sending",
    "templateId": null,
    "listId": "0b7c51e8-5df6-4e87-9fc2-d272dca63214",
    "tagId": "7c2ef4b1-94da-46df-b2c4-b390282adf64",
    "topicId": null,
    "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,
    "campaignUrl": "https://www.agentsmail.io/en/team/my-team/campaigns/4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "campaignEditorUrl": null,
    "campaignStatsUrl": null,
    "campaignPreviewUrl": null,
    "publicCampaignUrl": null
  }
}

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.