Modifier une campagne en brouillon

PATCH /api/v1/campaigns/{campaignId} Modifie une campagne en brouillon. Une campagne est créée avec une copie du HTML de son modèle, puis vit sa propre vie : cet endpoint modifie cette copie — le HTML réellement envoyé — sans toucher au modèle. Une campagne déjà envoyée ou en cours d'envoi est figée et renvoie 400. Tous les champs sont facultatifs ; seuls ceux que vous envoyez sont modifiés. tagId, topicId et sendingIdentityId suivent la même règle avec un null explicite : omettre le champ conserve la valeur en place, envoyer null l'efface. C'est le seul moyen de détacher un sujet éditorial d'un brouillon — voir Sujets. Les balises de fusion Mailchimp présentes dans le HTML sont converties comme à la création d'un modèle ; toute balise non prise en charge est renvoyée dans unsupportedTags.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERRefusé — 403
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 du brouillon à modifier

Corps de la requête

ChampTypeObligatoireDescription
contentstringnonLe HTML de l'e-mail
subjectstringnon1 à 200 caractères
previewTextstring | nullnonTexte d'aperçu, jusqu'à 200 caractères après suppression des espaces de début et de fin. null l'efface ; omis dans un PATCH, il est conservé. Rendu à l'emplacement de {{previewText}} ou {{preheader}}
preheaderstring | nullnonAlias compatible de previewText. Si les deux sont fournis, ils doivent être identiques après suppression des espaces, sinon 400
namestringnon1 à 100 caractères
listIdstringnonChange la cible de la campagne ; doit appartenir à l'organisation
tagIdstringnonRestreint la cible à un tag, ou null pour l'effacer
topicIdstringnonSujet éditorial que porte la campagne, ou null pour l'effacer
templateIdstringnonRattache un autre modèle d'origine ; doit appartenir à l'organisation
sendingIdentityIdstringnonChange l'adresse qui signe, ou null pour revenir à l'adresse par défaut
json
{"previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours."}
Utilisez un seul alias. Si les deux sont présents, ils doivent être identiques après suppression des espaces, null compris ; des valeurs contradictoires renvoient 400. Une chaîne vide supprime aussi le texte d'aperçu.

Exemple

bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID \
  -d '{ "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.", "content": "<html><body><div data-skip-in-text=\"true\" style=\"display:none;max-height:0;overflow:hidden;mso-hide:all;\">{{previewText}}</div><p>Hi {{firstName}}</p><a href=\"{{unsubscribeUrl}}\">Unsubscribe</a></body></html>" }'

Réponse

  • 400 Bad Request — champs invalides, texte d'aperçu de plus de 200 caractères, ou alias contradictoires.
  • 200 OK — l'appel a réussi.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
  • 404 Not Found — aucune ressource de ce type, ou elle appartient à une autre organisation. L'API ne confirme jamais l'existence d'un id à un appelant qui n'y a pas droit.
  • 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.namestringSon nom interne
data.subjectstringL'objet que voient les destinataires
data.previewTextstring | nullTexte d'aperçu enregistré ; égal à data.preheader
data.preheaderstring | nullLe texte d'aperçu affiché après l'objet, null s'il n'y en a pas
data.statusstringdraft, scheduled, paused, sending, sent, failed
data.listIdstringLa liste qu'elle cible
data.tagIdstringnull
data.topicIdstringnull
data.scheduledAtstringnull
data.sentAtstringnull
data.createdAtstringDate de création ISO
data.updatedAtstringDate ISO de la dernière modification
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": "draft",
    "listId": "0b7c51e8",
    "tagId": "7c2ef4b1",
    "topicId": null,
    "scheduledAt": null,
    "sentAt": null,
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z",
    "campaignUrl": "https://www.agentsmail.io/fr/team/my-team/campaigns/4d19c0a2",
    "campaignEditorUrl": "https://www.agentsmail.io/fr/team/my-team/campaigns/4d19c0a2/content",
    "campaignStatsUrl": null,
    "campaignPreviewUrl": null,
    "publicCampaignUrl": null
  }
}

Remarques

Le HTML doit contenir {{previewText}} ou {{preheader}}, généralement dans un bloc masqué. AgentsMail n'insère aucun bloc. Voir Balises de fusion.

Voir aussi