Listes

Les listes de diffusion vous permettent d'organiser vos abonnés en groupes pour des campagnes ciblées. Chaque enregistrement d'abonné appartient à une liste, mais la même adresse e-mail peut avoir des enregistrements distincts dans plusieurs listes, et les campagnes peuvent cibler une liste spécifique ou un segment de cette liste.

Créer une liste

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

Create list request

{
  "name": "Product Updates",
  "description": "Subscribers interested in product announcements"
}

Champ	Type	Requis	Description
`name`	string	Oui	Nom de la liste (doit être unique par espace de travail)
`description`	string	Non	Description de la liste

Create a mailing list

curl -X POST https://api.mail.land/v1/marketing/lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates", "description": "Product announcements" }'

Réponse

List response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 0,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Lister toutes les listes de diffusion

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

Paramètre	Type	Défaut	Description
`cursor`	string	-	Curseur opaque issu du `nextCursor` de la page précédente. À omettre pour la première page.
`limit`	int	20	Éléments par page
`search`	string	-	Recherche par nom
`isActive`	bool	-	Filtrer par statut actif
`sortBy`	string	-	Champ de tri
`sortDesc`	bool	false	Tri décroissant

List all mailing lists

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

List response

{
  "items": [
    {
      "id": "vtmlew96u277jq",
      "name": "Product Updates",
      "description": "Product announcements",
      "isActive": true,
      "subscriberCount": 2500,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-17T12:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Obtenir les détails d'une liste

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

Retourne les détails étendus incluant la répartition des abonnés :

Get list details

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

List detail response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 2500,
  "activeSubscribers": 2300,
  "unsubscribedCount": 150,
  "bouncedCount": 50,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Mettre à jour une liste

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

Update list request

{
  "name": "Product Announcements",
  "description": "Updated description",
  "isActive": true
}

Champ	Type	Requis	Description
`name`	string	Oui	Nom de la liste (doit être unique)
`description`	string	Non	Description de la liste
`isActive`	bool	Non	Statut actif (défaut : `true`)

isActive n'est qu'une étiquette : le définir sur false ne bloque pas l'envoi. Rien dans le code des campagnes ou du worker ne lit ce champ pour empêcher une campagne de cibler cette liste.

Update a mailing list

curl -X PUT https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Announcements",
    "description": "Updated description",
    "isActive": true
  }'

Supprimer une liste

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

Supprime la liste de diffusion. Les abonnés de cette liste ne sont pas supprimés, mais leur mailingListId est effacé (une clé étrangère SetNull). Les désinscriptions propres à la liste sont conservées lorsqu'une liste est supprimée.

Si un abonné de cette liste possède déjà un contact sans liste (par exemple parce qu'il faisait partie d'une autre liste supprimée auparavant), ce contact est conservé et son adhésion à cette liste n'est gardée que comme historique : elle n'apparaît plus dans les contacts et aucune campagne ni automatisation ne la cible. Ses désabonnements, preuves de consentement et historique de campagnes sont conservés.

Delete a mailing list

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

Réponses d'erreur

Statut	Code	Description
`400`	`VALIDATION_FAILED`	Le nom est obligatoire
`400`	`INVALID_REQUEST`	Une liste de diffusion avec ce nom existe déjà
`403`	`FORBIDDEN`	Permissions insuffisantes
`404`	`RESOURCE_NOT_FOUND`	Liste de diffusion introuvable

Prochaines étapes

Abonnés : ajoutez des abonnés à vos listes
Segments : créez des segments dynamiques au sein des listes
Campagnes : envoyez des campagnes à vos listes

Listes

Créer une listeCopier le lien de la section

RéponseCopier le lien de la section

Lister toutes les listes de diffusionCopier le lien de la section

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

Mettre à jour une listeCopier le lien de la section

Supprimer une listeCopier le lien de la section

Réponses d'erreurCopier le lien de la section

Prochaines étapesCopier le lien de la section

Sur cette page