Programmer une campagne

POST /api/v1/campaigns/{campaignId}/schedule Réserve l'envoi d'une campagne draft pour un instant futur, et répond 202. Appelé sur une campagne déjà scheduled, il la déplace au nouvel instant. Cet appel n'envoie rien : la campagne part d'elle-même à l'heure réservée.

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 unique d'une campagne

Corps de la requête

ChampTypeObligatoireDescription
scheduledAtstringouiInstant ISO 8601 avec un décalage explicite, au moins une minute dans le futur
json
{"scheduledAt": "2026-08-12T07:00:00Z"}

Exemple

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt": "2026-08-12T07:00:00Z"}' \
  "https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID/schedule"

Réponse

  • 202 Accepted — la campagne est scheduled pour l'instant renvoyé dans scheduledAt.
  • 400 Bad Request — scheduledAt est absent, sans décalage, passé ou à moins d'une minute (details précise le problème) ; ou le contenu n'a pas de lien de désabonnement.
  • 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 campagne 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.
  • 409 Conflict — le domaine d'envoi n'est pas encore vérifié, le solde ne couvre pas les destinataires de la campagne, sa liste a été retirée, ou la campagne est paused, sending, sent ou failed. Rien n'est réservé.
  • 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
data.campaignIdstringLa campagne programmée
data.statusstringToujours scheduled
data.scheduledAtstringL'instant réellement enregistré, en UTC, arrondi à la minute

Exemple de réponse

json
{
  "success": true,
  "data": {
    "campaignId": "6c6c6c6c-5555-4aaa-8bbb-999900001111",
    "status": "scheduled",
    "scheduledAt": "2026-08-12T07:00:00.000Z"
  }
}

Notes

Une date sans fuseau horaire est refusée, jamais interprétée comme UTC. 2026-08-12T09:00:00 répond 400 : l'API ne devine pas un décalage que vous n'avez pas écrit. Écrivez 2026-08-12T07:00:00Z, ou 2026-08-12T09:00:00+02:00 — les deux désignent le même instant.
  • La programmation est conservée à la minute près : les secondes transmises sont ignorées. Lisez scheduledAt dans la réponse pour connaître le départ exact.
  • Rappeler l'endpoint sur une campagne scheduled déplace le départ ; l'ancien horaire ne vaut plus. Une campagne n'a jamais plus d'un départ.
  • Une campagne paused répond 409 : reprenez-la dans l'application, ou remettez-la en brouillon avec Déprogrammer une campagne puis reprogrammez-la.
  • Pour envoyer tout de suite, utilisez Envoyer une campagne.
Ne programmez jamais sans l'accord humain explicite pour cette campagne précise. Une campagne programmée part d'elle-même ; l'accord pour un envoi ne couvre jamais le suivant.

Voir aussi