---
title: Contacts
description: Les personnes à qui vous envoyez des e-mails marketing, avec leur état d'abonnement et leurs propriétés personnalisées.
ai:
  exclude: true
---

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](/docs/fr/concepts/segments) et des [thématiques](/docs/fr/concepts/topics). 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](/docs/fr/concepts/unsubscribes).
- `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](/docs/fr/concepts/verification).
- `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.

```sh
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`).

```sh
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" }]'
```

```json
{
  "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](/docs/fr/concepts/verification).

## Événements

Chaque modification publie un événement de [webhook](/docs/fr/concepts/webhooks) : `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.
