Champs personnalisés

Les champs personnalisés stockent des données supplémentaires sur chaque contact, comme un nom d’entreprise, un forfait ou une date d’anniversaire. Vous définissez les champs une fois pour l’espace de travail, puis vous les remplissez sur les contacts et vous les utilisez pour filtrer les contacts, personnaliser les campagnes et démarrer des automatisations.

Types de champs

Chaque champ a un nom, affiché par le tableau de bord, et une clé, utilisée par l’API, les imports, les filtres et les balises de fusion. Les valeurs sont stockées sur le contact sous la forme d’un objet JSON indexé par clé de champ :

{
  "company": "Acme",
  "plan": "pro",
  "birthday": "1990-04-12",
  "interests": ["news", "offers"]
}

Créer un champ personnalisé

1. Ouvrez Custom fields. Accédez à Workspace›Settings›Custom fields et sélectionnez Add custom field.

2. Nommez le champ. Saisissez un Name, par exemple Company size. Emailit construit automatiquement la clé à partir du nom : en minuscules, chaque suite d’autres caractères étant remplacée par _. Company size devient ainsi company_size.

   Pour choisir la clé vous-même, sélectionnez Show advanced options et modifiez Key. Les clés sont toujours enregistrées sous cette forme en minuscules avec des tirets bas, et chaque clé ne peut exister qu’une fois par espace de travail.

3. Choisissez le type. Choisissez Text, Number, Date, Boolean, Select ou Multi select.

4. Ajoutez des options pour les champs à choix. Pour Select et Multi select, saisissez au moins une option et utilisez Add option pour en ajouter d’autres. Ces valeurs apparaissent dans la liste déroulante des contacts.

5. Enregistrez. Sélectionnez Create. Le champ apparaît sur chaque contact, dans les filtres de contacts et sous forme de balise de fusion dans les éditeurs de campagne.

La page Custom fields liste tous les champs avec leur nom, leur type et leurs options. Utilisez Edit pour renommer un champ, changer son type ou sa clé, ou modifier ses options.

Renseigner les valeurs

Via l’API, transmettez custom_fields à Créer un contact ou à Mettre à jour un contact :

curl https://api.emailit.com/v2/contacts/ada@example.com \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "company": "Acme",
      "plan": "pro",
      "birthday": "1990-04-12",
      "interests": ["news", "offers"]
    }
  }'

Règles à connaître :

• custom_fields remplace l’objet entier. Lors d’une mise à jour, incluez toutes les valeurs que vous voulez conserver, pas seulement celles qui changent.
• Utilisez les clés des champs, pas leurs noms. Les valeurs des clés non définies dans Custom fields sont stockées mais n’apparaissent pas dans le tableau de bord.
• Les dates doivent être au format YYYY-MM-DD. Emailit convertit en date les date-heures ISO et les cellules de date Excel. Tout autre format renvoie 400 avec « Custom field “Birthday” must be a date in YYYY-MM-DD format ». Les dates n’ont ni heure ni fuseau horaire.
• Les valeurs des champs à choix ne sont pas contrôlées par rapport aux options. Une valeur absente de la liste d’options est quand même stockée, et le tableau de bord continue de l’afficher.

Filtrer les contacts par champ personnalisé

Dans le tableau de bord, ouvrez Email Marketing›Contacts, sélectionnez Filter et choisissez le champ personnalisé par son nom. Les filtres sur les champs personnalisés comparent la valeur stockée sous forme de texte : utilisez equals, does not equal, contains, does not contain, starts with, ends with, is empty ou is not empty.

Via l’API, utilisez custom_fields.<key>.<condition> sur Lister les contacts et Exporter les contacts, avec les mêmes conditions textuelles (exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty) :

curl "https://api.emailit.com/v2/contacts?custom_fields.plan.exact=pro&custom_fields.company.contains=acme" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

Pour une plage, comme les anniversaires des années 1990, utilisez les paramètres filter[custom_fields.<key>][gte] et [lte]. Ils comparent le texte stocké, dont le tri est correct pour les dates YYYY-MM-DD :

curl -G "https://api.emailit.com/v2/contacts" \
  --data-urlencode "filter[custom_fields.birthday][gte]=1990-01-01" \
  --data-urlencode "filter[custom_fields.birthday][lte]=1999-12-31" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

Pour savoir comment les filtres se combinent, consultez Filtrage et tri.

Utiliser les champs personnalisés dans les campagnes

Dans le contenu et l’objet des campagnes, insérez un champ personnalisé avec la balise de fusion {{cf.<key>}}, par exemple {{cf.company}}. Les éditeurs de texte enrichi et Dragit listent vos champs personnalisés parmi leurs variables : vous n’avez pas besoin de saisir la clé.

<p>Hi {{first_name}}, here's what's new for {{cf.company}}.</p>

Si un contact n’a pas de valeur, la balise est remplacée par du vide. Les valeurs à choix multiple s’affichent sous forme de liste séparée par des virgules. Consultez Balises de fusion.

Utiliser les champs personnalisés dans les automatisations

• Déclencheur d’anniversaire de date. Choisissez un champ Date pour démarrer une exécution chaque année au mois et au jour qu’il contient, par exemple un anniversaire. Consultez Déclencheurs.
• Déclencheur de mise à jour du contact. Filtrez sur un champ personnalisé, ou sur sa valeur précédente, pour réagir à sa modification.
• Étape de condition. Créez des branches selon la valeur d’un champ personnalisé.
• Étape de modification du contact. Définissez un champ personnalisé en saisissant sa clé.

Référence de l’API

Les définitions des champs personnalisés se gèrent uniquement dans le tableau de bord. Les valeurs des contacts utilisent l’objet custom_fields de l’API des contacts, et le même objet est accepté quand vous ajoutez un abonné à une liste.

Voir aussi