Obtenir une campagne

GET /api/v1/campaigns/{campaignId} Renvoie une campagne avec son nombre de destinataires en temps réel et la progression de son envoi. recipientCount est calculé à partir de la cible actuelle ; ce n'est pas une estimation enregistrée.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERAutorisé
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 chemin

ParamètreTypeDescription
campaignIdstringIdentifiant unique d'une campagne

Exemple

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

Réponse

  • 200 OK — la campagne et ses informations d'envoi actuelles.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 404 Not Found — aucune campagne de ce type, ou elle appartient à une autre organisation.
  • 429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

ChampTypeDescription
successbooleanIndique si l'opération a réussi
dataobjectObjet campagne.
data.campaignUrlstring | nullPage de la campagne.
data.campaignEditorUrlstring | nullÉditeur du contenu pour un brouillon modifiable.
data.campaignStatsUrlstring | nullStatistiques d’une campagne envoyée.
data.campaignPreviewUrlstring | nullAperçu interne d’une campagne envoyée.
data.publicCampaignUrlstring | nullArchive partageable d’une campagne envoyée dont les archives publiques sont activées.
data.idstringIdentifiant unique de la campagne
data.namestringNom interne de la campagne
data.subjectstringObjet affiché aux destinataires
data.previewTextstring | nullTexte d'aperçu enregistré ; égal à data.preheader
data.preheaderstring | nullTexte d'aperçu affiché après l'objet ; null s'il n'y en a pas
data.contentstringContenu HTML envoyé aux destinataires
data.statusstringdraft, scheduled, paused, sending, sent, failed ou deleted
data.templateIdstring | nullModèle d'origine, si la campagne a été créée à partir d'un modèle
data.listIdstringListe ciblée par la campagne
data.tagIdstring | nullTag facultatif qui restreint la liste
data.topicIdstring | nullSujet éditorial que porte cette campagne, le cas échéant
data.sendingIdentityIdstring | nullIdentité d'expéditeur choisie ; null utilise l'identité par défaut
data.scheduledAtstring | nullHeure de départ programmée au format ISO 8601 ; conservée tant qu'elle est paused
data.sentAtstring | nullHeure de fin au format ISO 8601
data.createdAtstringHeure de création au format ISO 8601
data.updatedAtstringDernière modification de la campagne au format ISO 8601
data.recipientCountnumberContacts abonnés correspondant à la cible à cet instant
data.progress.totalnumberEnregistrements d'envoi créés pour la campagne
data.progress.sentnumberMessages confirmés comme envoyés
data.progress.failednumberMessages qui se sont soldés par un échec
data.progress.pendingnumberMessages pas encore tentés
data.progress.sendingnumberMessages actuellement réservés pour traitement
data.progress.staleSendingnumberMessages réservés dont la fenêtre de traitement a expiré
data.progress.lastActivityAtstring | nullDernière activité d'envoi réelle : sentAt pour un message expédié, heure de passage à l'état final pour un message en échec ou ignoré
data.progress.chunkSizenumberNombre de messages attribués à un lot de traitement
data.sendingEnabledbooleanIndique si l'envoi de campagnes est actuellement activé sur tout AgentsMail
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-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/fr/team/my-team/campaigns/4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "campaignEditorUrl": null,
    "campaignStatsUrl": null,
    "campaignPreviewUrl": null,
    "publicCampaignUrl": null
  }
}

Remarques

  • staleSending est inclus dans sending ; n'additionnez pas les deux valeurs.
  • Les ouvertures et les clics ne mettent pas à jour lastActivityAt.
  • Une valeur staleSending non nulle ne prouve pas qu'un message n'a pas été accepté. Ne le renvoyez pas automatiquement.
  • recipientCount exclut les contacts désabonnés, en rebond ou ayant porté plainte.

Voir aussi