Contacts

Gérez les contacts dans Contacts > Tous les contacts sur le tableau de bord, avec bird contacts depuis le terminal, via l'API des contacts ou avec l'un des SDK.

Joindre des contacts

Pour envoyer un e-mail à une personne, utilisez son adresse avec l'API d'envoi ; sa fiche de contact conserve ses informations pour les réutiliser. Pour joindre plusieurs personnes à la fois, envoyez un lot ou regroupez-les dans une audience et lancez une diffusion. L'enregistrement d'un contact ne déclenche aucun envoi à lui seul.

La page Contacts

La page Contacts affiche le nom du contact, ses identifiants, les audiences auxquelles il appartient et ses informations de création. Recherchez par nom, e-mail ou téléphone, puis sélectionnez une ligne pour ouvrir le contact. Utilisez les actions de l'en-tête pour ajouter un contact ou en importer plusieurs. L'affichage nécessite le droit de lecture email_marketing. L'ajout, la modification et la suppression nécessitent le droit d'écriture.

Contenu d'un contact

Chaque contact possède une adresse e-mail, un numéro de téléphone ou les deux, chacun unique dans votre espace de travail, ainsi qu'un nom et votre propre identifiant facultatifs :

Le tableau de bord déduit les libellés Email et SMS des identifiants présents. L'API renvoie email et phone_number ; elle ne renvoie pas de champ channels. Ces libellés n'établissent ni l'autorisation d'envoyer ni la joignabilité sur le canal.

Chaque contact possède également un ID préfixé par con_, ainsi que ses horodatages de création et de mise à jour. La référence de l'API contient la spécification complète des champs.

Propriétés de contact

Les propriétés de contact définissent le schéma typé des champs personnalisés d'un contact. Enregistrez une propriété pour votre espace de travail : chaque contact pourra ensuite avoir une valeur correspondante dans data. Déclarer le schéma à l'avance rend la personnalisation et la segmentation fiables : une valeur arrive toujours avec le type déclaré, sur lequel un modèle ou un filtre peut donc compter.

Gérez-les dans Contacts > Propriétés de contact. Chaque propriété possède une clé, un type et une valeur de repli facultative :

• La clé est le nom qui permet de référencer la valeur, par exemple plan_tier. Elle doit être en minuscules et commencer par une lettre (^[a-z][a-z0-9_]*$), et elle ne peut plus changer après sa création.
• Le type est l'un des suivants : string, number, boolean ou datetime. Il est lui aussi fixé à la création. Un datetime accepte un horodatage RFC 3339 avec un décalage explicite, comme 2026-01-15T11:30:00+02:00, que nous normalisons en UTC à la seconde près. Cette valeur est donc enregistrée et renvoyée sous la forme 2026-01-15T09:30:00Z. Une date seule, sans heure, est refusée. Le tableau de bord les désigne par Texte, Nombre, Vrai / faux et Date et heure.
• La valeur de repli est celle lue pour un contact qui n'a pas de valeur propre. Ainsi, l'absence de plan_tier peut renvoyer free plutôt qu'une valeur vide.

Définissez les valeurs des propriétés là où vous modifiez un contact. Le formulaire de contact du tableau de bord affiche un champ de saisie typé par propriété active, et la CLI comme l'API acceptent les mêmes clés dans data.

Archiver une propriété

L’archivage permet de retirer une propriété de contact. Bird conserve ses valeurs pour que vous puissiez la restaurer avec Désarchiver. Il n’existe pas de suppression définitive d’une propriété.

Une propriété archivée disparaît des sélecteurs de propriétés, y compris lors de la correspondance des colonnes d’import. Les nouvelles versions de template qui la lisent ne peuvent pas être publiées. L’erreur de publication nomme la propriété. Les templates déjà publiés continuent d’envoyer des messages et utilisent la valeur du contact ou la valeur de repli de la propriété.

Les contacts conservent leurs valeurs stockées. Vous pouvez toujours les lire et les mettre à jour via l’API et les imports. Les valeurs doivent correspondre au type de la propriété.

Si une automatisation publiée, même en pause, utilise la propriété dans un déclencheur ou une écriture de données de contact, l’archivage renvoie un conflit 409. Une exécution active qui écrit la propriété empêche aussi l’archivage. Retirez la propriété de ces automatisations ou archivez-les. Laissez les exécutions actives se terminer ou annulez-les, puis archivez à nouveau la propriété. L’erreur nomme les automatisations si vous avez le droit de les lire.

Désarchivez la propriété pour la restaurer avec ses valeurs. Elle réapparaît dans les sélecteurs et peut être utilisée dans de nouvelles versions de template. Sa clé reste réservée pendant l’archivage et compte dans la limite de 200 propriétés de l’espace de travail.

Importer et synchroniser des contacts

Pour importer une liste depuis la page Contacts, sélectionnez Importer et téléversez un fichier CSV, TSV ou Excel. Prévoyez un contact par ligne et une ligne d'en-tête avec les noms des colonnes. Un fichier peut contenir jusqu'à 50 000 contacts. Les fichiers CSV peuvent atteindre 50 Mo, et les fichiers de tableur 10 Mo.

La ligne d'en-tête aide à identifier chaque champ de contact. Les colonnes nommées "Email Address", "E-Mail" ou "Correo electrónico" correspondent toutes au champ e-mail. Une colonne contenant un nom complet est séparée en prénom et nom de famille. Si deux colonnes peuvent alimenter le même champ, celle dont les valeurs confirment le nom est retenue. Chaque colonne affiche quelques-unes de ses valeurs pour vous montrer son contenu, et un nom séparé est présenté à côté de sa valeur d'origine. Modifiez ces correspondances dans le menu déroulant de chaque colonne. Toutes les personnes du fichier peuvent être ajoutées à une ou plusieurs audiences pendant cette même importation.

Chaque ligne est associée à un contact existant d'après ses identifiants et le met à jour, ou crée un contact s'il est nouveau. Réimporter le même fichier effectue donc un upsert plutôt que d'accumuler des doublons. Avant toute écriture, le tableau de bord indique combien de lignes initiales ne peuvent pas être importées avec les correspondances actuelles. Après l'exécution, chaque ligne ignorée indique son numéro de ligne dans le fichier source et son erreur.

Le compteur de doublons de l'import désigne les lignes répétées au sein de votre fichier. Il se base sur l'adresse e-mail si elle est présente, ou sur le numéro de téléphone sinon. Les correspondances avec des contacts déjà présents dans votre espace de travail apparaissent comme des mises à jour lorsque le API les confirme.

“This row was not confirmed as saved” signifie que le tableau de bord n'a pas reçu de résultat confirmant cette ligne. La ligne a peut-être été enregistrée, même si les compteurs de créations et de mises à jour sont à zéro. Vérifiez quelques contacts concernés avant de réessayer. Gardez l'onglet d'import ouvert jusqu'à la fin ; le tableau de bord exécute l'import depuis cet onglet.

Pour synchroniser depuis votre propre base de données, scriptez le CLI ou appelez le point de terminaison batch. bird contacts create <email> en ajoute un. bird contacts batch en insère ou met à jour jusqu'à 1 000 en un seul appel. Utilisez un seul batch par exécution plutôt qu'une requête par personne pour maintenir votre liste de contacts synchronisée avec votre système.

const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"

contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
print(contact.id, contact.email)

contact, err := client.Contacts.Create(context.Background(), bird.ContactCreateParams{
	Email:     bird.Ptr("jane@acme.com"),
	FirstName: bird.Ptr("Jane"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(contact.Id)

$contact = $bird->contacts->create(
    (new ContactCreateRequest())
        ->setEmail('jane@acme.com')
        ->setFirstName('Jane'),
);
echo $contact->getId(); // "con_…"

bird contacts create alice@acme.com \
  --first-name Alice \
  --last-name Anderson \
  --phone-number +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "phone_number": "+31612345678",
    "first_name": "Alice",
    "last_name": "Anderson"
  }'

Chaque entrée du batch est automatiquement mise en correspondance sur les identifiants qu'elle fournit (adresse e-mail, numéro de téléphone ou identifiant externe), et le champ optionnel match_on force la correspondance sur un seul d'entre eux. Une entrée peut aussi définir des valeurs de propriétés personnalisées et ajouter directement chaque contact de la requête à des audiences via audience_ids. Chaque entrée réussit ou échoue indépendamment, et la réponse renvoie un résultat par entrée dans l'ordre de soumission :

{
  "data": [
    {
      "contact_id": "con_01ky7q5t51echr7mqj5c08423b",
      "entry": { "email": "alex@example.com", "phone_number": null, "external_id": null },
      "matched_on": "email",
      "status": "updated"
    },
    {
      "contact_id": "con_01ky7q6mxdfhe86c9dqyt866pz",
      "entry": { "email": "jamie@example.com", "phone_number": null, "external_id": null },
      "matched_on": null,
      "status": "created"
    },
    {
      "contact_id": "con_01ky7q7rv9e9pt4vkr0w0gxq5e",
      "entry": { "email": "casey@example.com", "phone_number": null, "external_id": "user_2214" },
      "matched_on": "external_id",
      "status": "updated"
    }
  ]
}

Si les identifiants d'une entrée pointent vers des contacts existants différents, l'entrée échoue avec un conflit à examiner. Corrigez l'enregistrement source avant de réessayer ; le batch ne fusionne pas ces contacts.

Deux comportements par défaut sont utiles pour une synchronisation. Un batch fusionne les clés data avec les données existantes du contact, de sorte qu'un import modifiant un seul attribut n'efface jamais les autres. Envoyez une valeur null pour effacer une clé, ou définissez data_mode: "replace" pour écraser l'intégralité de la map. Définissez votre propre external_id sur chaque contact, afin qu'une synchronisation ultérieure retrouve la même personne même après un changement d'adresse e-mail. Dans l'exemple de batch, user_2214 existe déjà, donc l'entrée est résolue vers ce contact et y inscrit la nouvelle adresse e-mail.

Supprimer un contact

La suppression d'un contact est définitive : l'enregistrement et ses appartenances aux audiences disparaissent, et rien ne permet de les récupérer. Les suppressions et les préférences restent toutefois intactes. Une adresse ayant subi un hard bounce reste sur votre liste de suppression, et une adresse désabonnée conserve sa préférence de désinscription après la suppression du contact, de sorte que supprimer quelqu'un ne le rend jamais discrètement de nouveau contactable par e-mail.

Étapes suivantes

• Audiences : regrouper des contacts dans des listes réutilisables
• Suppressions : la liste des adresses de l'espace de travail auxquelles nous ne livrons pas, séparée de vos contacts
• Envoi par lot : atteindre de nombreux destinataires en un seul appel, jusqu'à 100 messages par requête
• CLI : scripter les contacts, les propriétés et les audiences avec la commande bird
• Référence API : schémas complets des requêtes et des réponses