List campaigns

GET /api/v1/campaigns Lists campaigns in your organization, with the saved preview text under both compatible names.

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.

Query parameters

Parameter	Type	Description
`status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`search`	string	Matches the campaign name, case-insensitive
`page`	number	Defaults to `1`
`limit`	number	Defaults to `20`, capped at `100`

Example

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/campaigns?status=sent&limit=20"

Response

200 OK — the call succeeded.
401 Unauthorized — missing or invalid key, or its owner left the organization.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

data is an array of campaigns, with a pagination object next to it.

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data`	array	Campaign objects.
`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	Identifier of the campaign
`data[].name`	string	Its internal name
`data[].subject`	string	The subject recipients see
`data[].previewText`	string \| null	Saved preview text
`data[].preheader`	string \| null	Compatible alias, equal to `data[].previewText`
`data[].status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`data[].listId`	string	The list it targets
`data[].tagId`	string \| null	Optional tag narrowing the audience.
`data[].topicId`	string \| null	The editorial topic it carries, if any
`data[].scheduledAt`	string \	null
`data[].sentAt`	string \	null
`data[].createdAt` / `updatedAt`	string	ISO dates
`pagination`	object	`{total, page, limit, totalPages}`

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",
      "name": "Newsletter",
      "subject": "August news",
      "previewText": "Three new things this month",
      "preheader": "Three new things this month",
      "status": "sent",
      "listId": "0b7c51e8",
      "scheduledAt": "2026-08-23T10:22:05.000Z",
      "sentAt": "2026-08-23T10:22:05.000Z",
      "tagId": null,
      "createdAt": "2026-08-23T10:20:05.000Z",
      "updatedAt": "2026-08-23T10:22:05.000Z",
      "campaignUrl": "https://www.agentsmail.io/en/team/my-team/campaigns/4d19c0a2",
      "campaignEditorUrl": null,
      "campaignStatsUrl": "https://www.agentsmail.io/en/team/my-team/campaigns/4d19c0a2/stats",
      "campaignPreviewUrl": "https://www.agentsmail.io/en/team/my-team/campaigns/4d19c0a2/preview",
      "publicCampaignUrl": "https://www.agentsmail.io/en/public/my-team/newsletter"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}