Segments

Créez des segments dynamiques basés sur les attributs et le comportement des abonnés

Les segments sont des groupes d'abonnés dynamiques définis par des conditions. Contrairement aux listes statiques, les segments se mettent à jour automatiquement à mesure que les données des abonnés changent. Utilisez les segments pour cibler des campagnes sur des audiences spécifiques en fonction des attributs, de l'engagement et du comportement.

Types de correspondance

Type de correspondance	Valeur	Description
`All`	0	Toutes les conditions doivent correspondre (logique ET)
`Any`	1	N'importe quelle condition peut correspondre (logique OU)

Créer un segment

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

Create segment request

{
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "All",
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30"
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active"
    }
  ]
}

Champ	Type	Requis	Description
`name`	string	Oui	Nom du segment (unique par espace de travail)
`description`	string	Non	Description du segment
`matchType`	string	Non	`All` (par défaut) ou `Any`
`conditions`	array	Oui	Au moins une condition

Create a segment

curl -X POST https://api.mail.land/v1/marketing/segments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

Réponse

Segment response

{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Les réponses renvoient matchType en minuscules ("all" / "any") même si la requête de création/mise à jour accepte "All"/"Any".

Les champs de condition basés sur les ouvertures/clics (emailsopened, lastemailopenedat, etc.) incluent une activité automatisée, le préchargement d'Apple Mail Privacy Protection et les scanners de liens de sécurité, qui n'est pas filtrée aujourd'hui.

Un endpoint non documenté GET /{id}/preview existe également, renvoyant un échantillon d'abonnés correspondant actuellement aux conditions du segment.

Champs de condition

Champs texte

Champs : email, firstname, lastname, company, source, phone

Opérateur	Description	Valeur requise
`equals`	Correspondance exacte	Oui
`notequals`	Différent de	Oui
`contains`	Contient une sous-chaîne	Oui
`notcontains`	Ne contient pas	Oui
`startswith`	Commence par	Oui
`endswith`	Se termine par	Oui
`isempty`	Le champ est vide	Non
`isnotempty`	Le champ n'est pas vide	Non

Champs numériques

Champs : emailssent, emailsopened, emailsclicked

Opérateur	Description	Valeur requise	Valeur2 requise
`equals`	Égal à	Oui	Non
`notequals`	Différent de	Oui	Non
`greaterthan`	Supérieur à	Oui	Non
`greaterthanorequal`	Supérieur ou égal	Oui	Non
`lessthan`	Inférieur à	Oui	Non
`lessthanorequal`	Inférieur ou égal	Oui	Non
`between`	Entre deux valeurs	Oui	Oui

Champs date

Champs : createdat, subscribedat, lastemailsentat, lastemailopenedat, lastemailclickedat

Opérateur	Description	Valeur requise
`equals`	À une date précise	Oui (date ISO)
`before`	Avant la date	Oui (date ISO)
`after`	Après la date	Oui (date ISO)
`onorbefore`	Le ou avant	Oui (date ISO)
`onorafter`	Le ou après	Oui (date ISO)
`between`	Entre deux dates	Oui (value + value2)
`inlast`	Dans les N derniers jours	Oui (entier jours)
`isnull`	Date non définie	Non
`isnotnull`	Date définie	Non

Champs enum

Champ : status

Opérateur	Description	Valeurs
`equals`	Égal au statut	`Active`, `Unsubscribed`, `Bounced`, `Complained`
`notequals`	Différent de	Mêmes valeurs

Exemples de conditions

Email domain filter

{ "field": "email", "operator": "contains", "value": "example.com" }

High engagement filter

{ "field": "emailssent", "operator": "between", "value": "10", "value2": "50" }

Recent clickers

{ "field": "lastemailclickedat", "operator": "inlast", "value": "7" }

Missing first name

{ "field": "firstname", "operator": "isempty" }

Obtenir les métadonnées du segment

Récupérez tous les champs, opérateurs et valeurs enum disponibles pour la création de conditions de segment :

GET https://api.mail.land/v1/marketing/segments/metadata/fields

Get segment metadata

curl https://api.mail.land/v1/marketing/segments/metadata/fields \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Metadata response

{
  "fields": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "operators": ["equals", "notequals", "contains", "notcontains", "startswith", "endswith", "isempty", "isnotempty"],
      "enumValues": null
    },
    {
      "name": "status",
      "label": "Status",
      "type": "enum",
      "operators": ["equals", "notequals"],
      "enumValues": ["Active", "Unsubscribed", "Bounced", "Complained"]
    }
  ]
}

Lister les segments

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

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	-	Rechercher par nom ou description
`sortBy`	string	-	Champ de tri
`sortDesc`	bool	false	Tri décroissant

List segments

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

Obtenir les détails d'un segment

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

Renvoie le segment complet avec ses conditions :

Get segment details

curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Segment detail response

{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who engaged in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30",
      "value2": null
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active",
      "value2": null
    }
  ],
  "cachedCount": 450,
  "cachedAt": "2026-02-17T10:00:00Z",
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}

Prévisualiser les conditions

Prévisualisez le résultat des conditions avant de créer un segment. L'évaluation d'un segment se limite toujours aux abonnés à l'état Active, si bien qu'une condition comme status notequals Active ne correspond à personne.

POST https://api.mail.land/v1/marketing/segments/preview

Preview request

{
  "conditions": [
    { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
  ],
  "matchType": "All"
}

Preview segment conditions

curl -X POST https://api.mail.land/v1/marketing/segments/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
    ],
    "matchType": "All"
  }'

Preview response

{
  "count": 450,
  "sampleEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

Obtenir le nombre d'abonnés du segment

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

Get segment count

curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/count \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Count response

{
  "segmentId": "0qe306asbapwvd",
  "count": 450
}

Actualiser le cache du segment

Forcer un recomptage des abonnés correspondants :

POST https://api.mail.land/v1/marketing/segments/{id}/refresh

Refresh segment cache

curl -X POST https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refresh response

{
  "segmentId": "0qe306asbapwvd",
  "count": 460,
  "refreshedAt": "2026-02-17T12:30:00Z"
}

Dupliquer un segment

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

Crée un nouveau segment avec des conditions clonées. Le paramètre name est optionnel.

Duplicate a segment

curl -X POST "https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/duplicate?name=Copy%20of%20Segment" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Mettre à jour un segment

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

Le corps de la requête correspond à la requête de création. La mise à jour d'un segment actualise automatiquement son nombre mis en cache.

Update a segment

curl -X PUT https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users (Updated)",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "14" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

Supprimer un segment

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

La suppression d'un segment le détache de toute campagne à l'état Draft ou Scheduled qui le cible (le segmentId de la campagne est effacé), ce qui la laisse sans audience : l'envoyer renvoie 422 ou ne délivre à personne. Une campagne déjà à l'état Sending n'est pas affectée, car ses destinataires ont déjà été résolus.

Delete a segment

curl -X DELETE https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Réponses d'erreur

Statut	Code	Description
`400`	`VALIDATION_FAILED`	Nom ou conditions invalides
`400`	`INVALID_REQUEST`	Le nom du segment existe déjà
`403`	`FORBIDDEN`	Permissions insuffisantes
`404`	`RESOURCE_NOT_FOUND`	Segment introuvable

Étapes suivantes

Campagnes : cibler les campagnes avec des segments
Automatisations : les automatisations ne se déclenchent actuellement pas sur l'appartenance à un segment
Abonnés : gérer les contacts dans vos segments

Segments

Types de correspondanceCopier le lien de la section

Créer un segmentCopier le lien de la section

RéponseCopier le lien de la section

Champs de conditionCopier le lien de la section

Champs texteCopier le lien de la section

Champs numériquesCopier le lien de la section

Champs dateCopier le lien de la section

Champs enumCopier le lien de la section

Exemples de conditionsCopier le lien de la section

Obtenir les métadonnées du segmentCopier le lien de la section

Lister les segmentsCopier le lien de la section

Obtenir les détails d'un segmentCopier le lien de la section

Prévisualiser les conditionsCopier le lien de la section

Obtenir le nombre d'abonnés du segmentCopier le lien de la section

Actualiser le cache du segmentCopier le lien de la section

Dupliquer un segmentCopier le lien de la section

Mettre à jour un segmentCopier le lien de la section

Supprimer un segmentCopier le lien de la section

Réponses d'erreurCopier le lien de la section

Étapes suivantesCopier le lien de la section

Sur cette page