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 renvoie409. Une adresse qui ne pourra jamais recevoir d’e-mail (par exempleexample.com, un nom en.testou un domaine sans serveur de messagerie) renvoie422.first_name,last_name.unsubscribed: votre désinscription à l’échelle de l’équipe. Tant qu’elle vauttrue, 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 avecdomain_id,nameetunsubscribed_at. Les e-mails de ces domaines ignorent le contact, et vos autres domaines continuent de l’atteindre. Voir Désinscriptions.verification_statusetverified_at: en lecture seule. Le résultat de la dernière vérification approfondie du contact,nulltant qu’il n’est pas vérifié. Voir Vérification.properties: des valeurs personnalisées commeplan: "pro"oucity: "Berlin". Les valeurs sont des chaînes ou des nombres (pas d’objets ni de tableaux imbriqués, qui renvoient422), avec au plus 100 clés par contact. Les propriétés alimentent les champs de fusion des templates et les filtres de segments.PATCHles fusionne clé par clé, et une valeurnullsupprime 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 avec409(existant) ou422(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.