Campagnes

Créez et gérez des campagnes d'e-mail marketing. MailLand gère la sélection des destinataires, l'envoi, le suivi des livraisons et les analytiques d'engagement pour chaque campagne.

Cycle de vie d'une campagneCopier le lien de la section

Chaque campagne suit un flux d'états défini :

Transitions autorisées :

• Draft → Scheduled (planifier) ou Sending (envoyer immédiatement) ou Cancelled (annuler)
• Scheduled → Sending ou Cancelled : la replanification d'une campagne Scheduled n'est pas prise en charge
• Sending → Sent, Paused, Cancelled ou Failed
• Paused → Sending (reprendre)
• Sent ou Cancelled → archivée

Types de campagnesCopier le lien de la section

PersonnalisationCopier le lien de la section

Les lignes d'objet et le contenu des campagnes prennent en charge les balises de fusion {{variable}}, substituées par destinataire à partir du propre enregistrement de cet abonné.

<p>Hi {{firstName}}, here's what's new this month.</p>

Les anciennes orthographes en snake_case ({{first_name}}, {{last_name}}, {{full_name}}, {{subscriber_id}}) continuent de fonctionner comme alias.

Créer une campagneCopier le lien de la section

POST https://api.mail.land/v1/marketing/campaigns

{
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "replyTo": "[email protected]",
  "htmlContent": "<html>...</html>",
  "textContent": "Plain text version...",
  "type": 0,
  "mailingListId": "ddv6ou6kz4wbto",
  "segmentId": "x4xa3ep1zmqq0b"
}

* Fournissez mailingListId ou segmentId : l'un des deux est requis sauf si templateId est défini.

curl -X POST https://api.mail.land/v1/marketing/campaigns \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Newsletter",
    "subject": "What'\''s new in February",
    "fromName": "MailLand Team",
    "fromEmail": "[email protected]",
    "htmlContent": "<html><body><h1>Hello!</h1></body></html>",
    "mailingListId": "ddv6ou6kz4wbto"
  }'

RéponseCopier le lien de la section

{
  "id": "uivozyvucowj9w",
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "status": "draft",
  "statusName": "Draft",
  "type": 0,
  "typeName": "Regular",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Main Newsletter",
  "segmentId": null,
  "segmentName": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Lister les campagnesCopier le lien de la section

GET https://api.mail.land/v1/marketing/campaigns

curl "https://api.mail.land/v1/marketing/campaigns?limit=20&status=3" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    {
      "id": "uivozyvucowj9w",
      "name": "February Newsletter",
      "subject": "What's new in February",
      "status": "sent",
      "statusName": "Sent",
      "type": 0,
      "typeName": "Regular",
      "mailingListId": "ddv6ou6kz4wbto",
      "mailingListName": "Main Newsletter",
      "totalRecipients": 5000,
      "totalSent": 4980,
      "totalDelivered": 4900,
      "totalOpened": 1520,
      "totalClicked": 195,
      "totalBounced": 45,
      "totalUnsubscribed": 12,
      "sentAt": "2026-02-15T10:00:00Z",
      "completedAt": "2026-02-15T10:35:00Z",
      "createdAt": "2026-02-14T08:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Obtenir les détails d'une campagneCopier le lien de la section

GET https://api.mail.land/v1/marketing/campaigns/{id}

Retourne le CampaignDetailDto complet incluant le contenu HTML, toutes les statistiques et les taux d'engagement calculés :

curl https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "id": "uivozyvucowj9w",
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "replyTo": "[email protected]",
  "status": "sent",
  "statusName": "Sent",
  "type": 0,
  "typeName": "Regular",
  "htmlContent": "<html>...</html>",
  "textContent": "Plain text...",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Main Newsletter",
  "totalRecipients": 5000,
  "totalSent": 4980,
  "totalDelivered": 4900,
  "totalOpened": 1520,
  "totalClicked": 195,
  "totalBounced": 45,
  "totalUnsubscribed": 12,
  "totalComplaints": 2,
  "deliveryRate": 98.39,
  "openRate": 31.02,
  "clickRate": 3.98,
  "clickToOpenRate": 12.83,
  "bounceRate": 0.9,
  "unsubscribeRate": 0.24,
  "openTrackingEnabled": true,
  "clickTrackingEnabled": true,
  "sentAt": "2026-02-15T10:00:00Z",
  "completedAt": "2026-02-15T10:35:00Z",
  "createdAt": "2026-02-14T08:00:00Z",
  "updatedAt": "2026-02-15T10:35:00Z"
}

Taux d'engagementCopier le lien de la section

Les taux sont calculés côté serveur à partir des compteurs bruts (ouvertures et clics sont uniques par destinataire). deliveryRate et bounceRate sont des taux sur les messages envoyés ; openRate, clickRate et unsubscribeRate sont des taux sur les messages délivrés ; clickToOpenRate (CTOR) rapporte les clics aux ouvertures et reste une mesure distincte de clickRate. Un taux est un pourcentage sans plafond (clickToOpenRate peut dépasser 100) et vaut null, jamais 0, lorsqu'il est indisponible : son dénominateur est 0 ou le suivi nécessaire est désactivé sur le compte (openTrackingEnabled / clickTrackingEnabled indiquent le réglage actuel). Pour combiner des campagnes, additionnez les compteurs et divisez une seule fois ; ne faites pas la moyenne des pourcentages. La liste renvoie les mêmes champs pour chaque campagne.

Mettre à jour une campagneCopier le lien de la section

PUT https://api.mail.land/v1/marketing/campaigns/{id}

Seules les campagnes à l'état Draft ou Scheduled peuvent être mises à jour. Le corps de la requête correspond à la requête de création, à l'exception de type, qui ne peut pas être modifié.

curl -X PUT https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Newsletter (Updated)",
    "subject": "What'\''s new in February - updated",
    "fromName": "MailLand Team",
    "fromEmail": "[email protected]",
    "htmlContent": "<html><body><h1>Updated!</h1></body></html>",
    "mailingListId": "ddv6ou6kz4wbto"
  }'

Planifier une campagneCopier le lien de la section

POST https://api.mail.land/v1/marketing/campaigns/{id}/schedule

{
  "scheduledAt": "2026-02-20T14:00:00Z"
}

L'heure scheduledAt doit être dans le futur. Le statut de la campagne passe à Scheduled et le CampaignWorker la prend en charge à l'heure planifiée.

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/schedule \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-02-20T14:00:00Z" }'

Envoi immédiatCopier le lien de la section

POST https://api.mail.land/v1/marketing/campaigns/{id}/send

Envoie la campagne immédiatement. Le statut de la campagne passe à Sending et le CampaignWorker commence à traiter les destinataires.

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/send \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Pause et repriseCopier le lien de la section

Mettre en pause une campagne en cours d'envoi :

POST https://api.mail.land/v1/marketing/campaigns/{id}/pause

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/pause \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Reprendre une campagne en pause :

POST https://api.mail.land/v1/marketing/campaigns/{id}/resume

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

La mise en pause arrête le CampaignWorker de traiter les destinataires restants. Les e-mails déjà envoyés ne sont pas affectés. La reprise continue là où elle s'était arrêtée.

Annuler une campagneCopier le lien de la section

POST https://api.mail.land/v1/marketing/campaigns/{id}/cancel

Annule une campagne Draft, Scheduled ou Sending. Les e-mails déjà envoyés ne sont pas rappelés.

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/cancel \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Dupliquer une campagneCopier le lien de la section

POST https://api.mail.land/v1/marketing/campaigns/{id}/duplicate?name=Copy%20of%20Newsletter

Crée une nouvelle campagne Draft avec tous les paramètres copiés de l'original. Le paramètre de requête name est optionnel.

curl -X POST "https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/duplicate?name=Copy%20of%20Newsletter" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Archiver et désarchiverCopier le lien de la section

Archiver une campagne Sent ou Cancelled :

POST https://api.mail.land/v1/marketing/campaigns/{id}/archive

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/archive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Désarchiver une campagne archivée :

POST https://api.mail.land/v1/marketing/campaigns/{id}/unarchive

curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/unarchive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Les campagnes archivées sont masquées de la vue de liste par défaut sauf si includeArchived=true est passé.

Destinataires de la campagneCopier le lien de la section

Obtenez les destinataires paginés avec le statut de livraison pour une campagne :

GET https://api.mail.land/v1/marketing/campaigns/{id}/recipients

curl "https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/recipients?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    {
      "email": "[email protected]",
      "status": "Opened",
      "sentAt": "2026-02-15T10:00:30Z",
      "deliveredAt": "2026-02-15T10:00:32Z",
      "openedAt": "2026-02-15T11:15:00Z",
      "clickedAt": "2026-02-15T11:16:30Z",
      "bouncedAt": null,
      "complainedAt": null,
      "unsubscribedAt": null,
      "openCount": 2,
      "clickCount": 1,
      "bounceReason": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Statuts des destinatairesCopier le lien de la section

Supprimer une campagneCopier le lien de la section

DELETE https://api.mail.land/v1/marketing/campaigns/{id}

Supprime définitivement une campagne et ses données de destinataires. Seules les campagnes au statut Draft ou Scheduled peuvent être supprimées ; la suppression de tout autre statut renvoie 404, archivez plutôt une campagne envoyée.

curl -X DELETE https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Réponses d'erreurCopier le lien de la section

Étapes suivantesCopier le lien de la section

• Abonnés : gérer vos contacts abonnés
• Listes : organiser les abonnés en listes de diffusion
• Segments : cibler les campagnes avec des segments dynamiques
• Automatisations : configurer des séquences d'e-mails basées sur des déclencheurs