Lister les campagnes

GET /api/v1/campaigns Liste les campagnes de votre organisation, avec le texte d'aperçu enregistré sous ses deux noms compatibles.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Autorisé

Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de requête

Paramètre	Type	Description
`status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`search`	string	Recherche dans le nom de la campagne, sans tenir compte de la casse
`page`	number	`1` par défaut
`limit`	number	`20` par défaut, plafonné à `100`

Exemple

bash

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

Réponse

200 OK — l'appel a réussi.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

data est un tableau de campagnes, accompagné d'un objet pagination.

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data`	array	Objets campagne.
`data[].campaignUrl`	string \| null	Page de la campagne.
`data[].campaignEditorUrl`	string \| null	Éditeur du contenu pour un brouillon modifiable.
`data[].campaignStatsUrl`	string \| null	Statistiques d’une campagne envoyée.
`data[].campaignPreviewUrl`	string \| null	Aperçu interne d’une campagne envoyée.
`data[].publicCampaignUrl`	string \| null	Archive partageable d’une campagne envoyée dont les archives publiques sont activées.
`data[].id`	string	Identifiant de la campagne
`data[].name`	string	Son nom interne
`data[].subject`	string	L'objet que voient les destinataires
`data[].previewText`	string \| null	Texte d'aperçu enregistré
`data[].preheader`	string \| null	Alias compatible, égal à `data[].previewText`
`data[].status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`data[].listId`	string	La liste qu'elle cible
`data[].tagId`	string \| null	Étiquette facultative qui restreint la cible.
`data[].topicId`	string \| null	Le sujet éditorial qu'elle porte, le cas échéant
`data[].scheduledAt`	string \	null
`data[].sentAt`	string \	null
`data[].createdAt` / `updatedAt`	string	Dates ISO
`pagination`	object	`{total, page, limit, totalPages}`

Les cinq liens sont des URL absolues dans la langue de l’organisation (en par défaut). Les liens indisponibles valent null ; ils sont tous null si l’organisation n’a pas de slug d’URL. Les liens internes nécessitent une connexion et les droits sur l’organisation ; seul publicCampaignUrl est public. Les agents API et MCP affichent les liens pertinents non nuls en Markdown cliquable, par exemple [Ouvrir la campagne](campaignUrl) en utilisant l’URL reçue. Créer ou consulter une campagne ne la publie pas.

Exemple de réponse

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/fr/team/my-team/campaigns/4d19c0a2",
      "campaignEditorUrl": null,
      "campaignStatsUrl": "https://www.agentsmail.io/fr/team/my-team/campaigns/4d19c0a2/stats",
      "campaignPreviewUrl": "https://www.agentsmail.io/fr/team/my-team/campaigns/4d19c0a2/preview",
      "publicCampaignUrl": "https://www.agentsmail.io/fr/public/my-team/newsletter"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}