Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

Contacts

Les personnes à qui vous envoyez des e-mails marketing, avec leur état d'abonnement et leurs propriétés personnalisées.

Un contact est une adresse e-mail dans la liste de votre équipe. Chaque adresse n’apparaît qu’une fois (la casse n’est pas prise en compte), et vous choisissez qui reçoit une campagne avec des segments et des thématiques. Gérez les contacts dans le tableau de bord, sous Contacts, ou via l’API.

Ce que contient un contact

  • email : l’adresse. Créer un second contact avec la même adresse renvoie 409. Une adresse qui ne pourra jamais recevoir d’e-mail (par exemple example.com, un nom en .test ou un domaine sans serveur de messagerie) renvoie 422.
  • first_name, last_name.
  • unsubscribed : votre désinscription à l’échelle de l’équipe. Tant qu’elle vaut true, le contact ne reçoit aucun e-mail marketing d’aucun de vos domaines. Vous seul la définissez ; la désinscription d’un destinataire ne la modifie jamais.
  • unsubscribed_domains : en lecture seule. Les domaines dont le contact s’est désinscrit via un lien de désinscription, chacun avec domain_id, name et unsubscribed_at. Les e-mails de ces domaines ignorent le contact, et vos autres domaines continuent de l’atteindre. Voir Désinscriptions.
  • verification_status et verified_at : en lecture seule. Le résultat de la dernière vérification approfondie du contact, null tant qu’il n’est pas vérifié. Voir Vérification.
  • properties : des valeurs personnalisées comme plan: "pro" ou city: "Berlin". Les valeurs sont des chaînes ou des nombres (pas d’objets ni de tableaux imbriqués, qui renvoient 422), avec au plus 100 clés par contact. Les propriétés alimentent les champs de fusion des templates et les filtres de segments. PATCH les fusionne clé par clé, et une valeur null supprime la clé.

Créer et lire

POST /contacts, GET /contacts, GET /contacts/{id}, PATCH /contacts/{id} et DELETE /contacts/{id}. Dans {id}, vous pouvez utiliser l’identifiant du contact ou son adresse e-mail.

curl -X POST "https://api.billionsend.com/contacts" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@acme.com",
    "first_name": "Ana",
    "properties": { "plan": "pro" }
  }'

Ajoutez include=properties,topics à GET /contacts ou GET /segments/{id}/contacts pour obtenir dans la même réponse les propriétés et les choix de thématiques de chaque contact. POST /contacts/batch/get lit jusqu’à 1 000 contacts par identifiant ou adresse e-mail en un seul appel, dans l’ordre de la requête ; les adresses qui ne correspondent à rien sont listées sous missing.

PATCH /contacts/{id}/topics définit les choix de thématiques d’un contact, et GET /contacts/{id}/topics les relit avec les valeurs par défaut des thématiques appliquées.

POST /contacts/{id}/preferences-link renvoie un lien vers la page de préférences du contact, que vous pouvez ouvrir depuis un écran de paramètres de votre produit. Le lien n’expire pas et permet à celui qui le détient de modifier les choix de ce contact : ne le donnez qu’au contact lui-même. Il ouvre la page par défaut de l’équipe et désinscrit le contact de tous les domaines.

Création en masse

POST /contacts/batch accepte de 1 à 1 000 contacts dans une requête et les écrit ensemble.

on_conflict indique ce qui se passe quand une adresse existe déjà ou se répète dans le lot :

  • error (par défaut) : cet élément échoue avec 409 (existant) ou 422 (répétition).
  • skip : le contact existant reste tel quel.
  • upsert : l’élément est fusionné dans le contact existant. Les noms seulement si vous les envoyez, les propriétés clé par clé, les segments sont ajoutés, les thématiques mises à jour.

Un lot ne réabonne jamais personne : unsubscribed: false sur un contact déjà désinscrit est ignoré. Utilisez PATCH /contacts/{id} pour cela.

L’en-tête x-batch-validation choisit strict (par défaut : un seul élément invalide rejette tout le lot) ou permissive (les éléments valides sont écrits, les échecs sont listés dans errors).

curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
{
  "data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
  "counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
  "errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}

Suppression en masse

POST /contacts/batch/remove supprime jusqu’à 1 000 contacts par ids ou par emails (l’un des deux) et renvoie ceux qu’il a supprimés. Ajoutez erase: true pour retirer aussi chaque adresse de l’historique des e-mails, des charges utiles d’événements et des journaux d’API. DELETE /contacts/{id}?erase=true fait la même chose pour un seul contact.

Import et export CSV

Dans le tableau de bord, Contacts importe un CSV et exporte la vue actuelle (y compris avec un filtre de segment, de thématique ou de domaine) vers un CSV. L’export contient une colonne unsubscribed et une colonne unsubscribed_domains (* désigne toute l’équipe). Les lignes dont l’adresse ne pourra jamais recevoir d’e-mail sont ignorées. Avec un forfait payant, la fenêtre d’import peut aussi vérifier les nouvelles adresses, voir Vérification.

Événements

Chaque modification publie un événement de webhook : contact.created, contact.updated, contact.deleted, contact.unsubscribed, contact.resubscribed, contact.topic_opt_in et contact.topic_opt_out.

Limites

Free Starter, Pro, Scale
Contacts par équipe 1 000 Illimité

Au-delà de la limite, la création d’un contact renvoie 403 plan_limit_reached. Les contacts existants restent modifiables.

Cette page vous a-t-elle été utile ?