Contacts
Gérez les profils de contacts et les champs personnalisés, en masse ou un par un.
Créer un contact
Crée un contact et l’inscrit éventuellement à des listes de contacts.
/contactsNécessite une clé API full. Les adresses e-mail sont uniques au sein d’un espace de travail et enregistrées en minuscules ; créer un contact qui existe déjà renvoie 409 avec le contact existant dans existing. Déclenche contact.created, et subscriber.created pour chaque liste. Consultez Contacts.
Paramètres du corps
emailstringobligatoirefirst_namestringlast_namestringcustom_fieldsobjectValeurs par clé de champ personnalisé, par exemple {"company": "Analytical Engines"}. Les valeurs des champs de type date doivent être au format YYYY-MM-DD. Les clés qui ne correspondent à aucun champ personnalisé sont enregistrées telles quelles.
audiencesstring[]aud_…) auxquelles inscrire le contact. Les ID qui n’existent pas dans l’espace de travail sont ignorés.unsubscribedbooleanpar défaut : falsetrue pour créer le contact à l’état désinscrit. Les campagnes ignorent les contacts désinscrits, et leurs inscriptions aux listes sont créées à l’état désinscrit.
Réponse
Renvoie 201 avec l’objet contact. Ici, audiences contient chaque liste avec son id, son name et son statut subscribed. Pour tous les champs, consultez Récupérer un contact.
Renvoie 422 avec usage lorsqu’une liste a atteint la limite d’abonnés de votre forfait. Dans ce cas, aucun contact n’est créé.
{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
}{
"error": "Custom field \"Birthday\" must be a date in YYYY-MM-DD format"
}{
"error": "Contact with this email already exists",
"existing": {
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
}
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Récupérer un contact
Récupère un contact avec ses champs personnalisés et ses inscriptions aux listes de contacts.
/contacts/{id}Nécessite une clé API full.
Paramètres de chemin
idstringobligatoirecon_…) ou son adresse e-mail, encodée pour l’URL.Réponse
Renvoie l’objet contact.
objectstringcontact.idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject{} s’il n’y en a aucun.unsubscribedbooleantrue si le contact s’est désinscrit de toutes les campagnes.audiencesobject[]Les listes de contacts auxquelles appartient le contact, chacune avec id, name et un objet subscriber : id (sub_…), subscribed, subscribed_at, unsubscribed_at, created_at et updated_at.
created_atstringupdated_atstring{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscriber": {
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}
}
],
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}{
"error": "Contact not found"
}Mettre à jour un contact
Met à jour un contact. Seuls les champs que vous envoyez sont modifiés.
/contacts/{id}Nécessite une clé API full. Déclenche contact.updated, avec les valeurs précédentes des champs modifiés dans previous. Modifier audiences déclenche aussi subscriber.created et subscriber.deleted pour les inscriptions ajoutées et supprimées.
Paramètres de chemin
idstringobligatoirecon_…) ou son adresse e-mail, encodée pour l’URL.Paramètres du corps
emailstringfirst_namestringlast_namestringcustom_fieldsobjectunsubscribedbooleantrue pour désinscrire le contact de toutes les campagnes, false pour le réinscrire. Les inscriptions existantes aux listes conservent leur propre statut.audiencesstring[]La liste complète des ID des listes de contacts auxquelles le contact doit appartenir. Le contact est ajouté aux listes dont il ne fait pas encore partie et retiré de celles qui ne figurent pas dans votre tableau. Envoyez [] pour le retirer de toutes les listes. Pour ajouter ou retirer une seule liste sans les énumérer toutes, utilisez Ajouter un abonné ou Supprimer un abonné.
Réponse
Renvoie le contact mis à jour, au même format que Récupérer un contact. Une requête sans aucun de ces champs renvoie 400.
curl -X POST https://api.emailit.com/v2/contacts/ada%40example.com \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"custom_fields": { "company": "Analytical Engines", "plan": "business" },
"audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}'{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Augusta",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscriber": {
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}
}
],
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-02T09:03:17.000000Z"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, unsubscribed, audiences"
}{
"error": "Contact not found"
}{
"error": "Another contact with this email already exists"
}Lister les contacts
Renvoie une page de contacts, du plus récent au plus ancien.
/contactsNécessite une clé API full. Utilisez les mêmes paramètres avec Exporter des contacts pour télécharger tous les résultats dans un fichier.
Paramètres de requête
pageintegerpar défaut : 1limitintegerpar défaut : 10searchstringq fonctionne aussi.audience_idstringaud_…).unsubscribedbooleantrue ou false. Uniquement les contacts ayant ce statut de désinscription.sortstringpar défaut : created_atemail, first_name, last_name, name, audiences, created_at ou updated_at.orderstringpar défaut : descasc ou desc. Sur cet endpoint, order est le sens du tri, pas la clé de tri.matchstringpar défaut : allall ou or. Mode de combinaison des filtres ci-dessous.Filtres
Ajoutez des filtres sous la forme key.condition=value, par exemple email.ends_with=@acme.com ou custom_fields.plan.exact=pro. Consultez Filtrage et tri.
| Clé | Type | Remarques |
|---|---|---|
email |
chaîne | |
first_name |
chaîne | |
last_name |
chaîne | |
name |
chaîne | Prénom et nom de famille séparés par une espace. |
audiences |
chaîne | Le premier nom de liste du contact dans l’ordre alphabétique. |
unsubscribed |
booléen | |
created_at |
date | |
updated_at |
date | |
audience_id |
chaîne | Uniquement exact et not_exact. La valeur est un ID de liste. |
custom_fields.<key> |
chaîne | Remplacez <key> par la clé d’un champ personnalisé. Les valeurs sont comparées comme du texte. |
Les anciens paramètres filter[audience_id], filter[unsubscribed] et filter[custom_fields][<key>] fonctionnent toujours.
Réponse
dataobject[]audiences sous la forme id, name et subscribed. Consultez Récupérer un contact.total_recordsintegernext_page_urlstring | nullnull. Consultez Pagination.previous_page_urlstring | nullnull.curl -G https://api.emailit.com/v2/contacts \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
--data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
--data-urlencode "custom_fields.plan.exact=pro" \
--data-urlencode "sort=email" \
--data-urlencode "order=asc" \
--data-urlencode "limit=100"{
"data": [
{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
},
{
"object": "contact",
"id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
"email": "grace@example.com",
"first_name": "Grace",
"last_name": "Hopper",
"custom_fields": {},
"unsubscribed": true,
"audiences": [],
"created_at": "2026-09-28T07:55:02.118342Z",
"updated_at": "2026-09-30T18:11:40.902215Z"
}
],
"total_records": 2,
"next_page_url": null,
"previous_page_url": null
}Mettre à jour des contacts en masse
Exécute une action sur 100 contacts au maximum en une seule requête.
/contacts/bulkNécessite une clé API full. Chaque ID doit correspondre à un contact de l’espace de travail ; sinon, rien n’est modifié et la réponse indique les ID manquants dans missing. Chaque contact déclenche les mêmes événements qu’avec les endpoints portant sur un seul contact. Si la liste de contacts atteint la limite d’abonnés de votre forfait pendant add_to_audience, la requête s’arrête avec 422, et les contacts traités jusque-là restent ajoutés.
| Action | Effet |
|---|---|
delete |
Supprime les contacts et leurs inscriptions aux listes, comme Supprimer un contact. |
add_to_audience |
Ajoute les contacts à audience_id. Les contacts qui y figurent déjà restent inchangés. |
remove_from_audience |
Retire les contacts de audience_id. |
unsubscribe |
Définit unsubscribed sur true : les campagnes ignorent alors ces contacts. |
resubscribe |
Définit unsubscribed sur false. |
Paramètres du corps
actionstringobligatoiredelete, add_to_audience, remove_from_audience, unsubscribe ou resubscribe.idsstring[]obligatoirecon_…), de 1 à 100. Les adresses e-mail ne sont pas acceptées ici. Les doublons sont ignorés.audience_idstringadd_to_audience et remove_from_audience.Réponse
objectstringcontact_bulk.actionstringprocessedintegeridsstring[]{
"object": "contact_bulk",
"action": "add_to_audience",
"processed": 2,
"ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}{
"error": "A maximum of 100 contacts can be updated per request"
}{
"error": "One or more contacts were not found",
"missing": ["con_4K3pZc1Q9nWm2LrT8vYb5Hd0XaE"]
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Exporter des contacts
Télécharge les contacts correspondants dans un fichier CSV ou XLSX.
/contacts/exportNécessite une clé API full. Accepte les mêmes paramètres de recherche, de filtre et de tri que Lister les contacts, transmis dans la chaîne de requête, sans pagination. POST /contacts/export fonctionne de la même manière. Un export peut inclure 10 000 contacts au maximum ; si davantage de contacts correspondent, la requête renvoie 422 : affinez alors les filtres.
Paramètres de requête
formatstringpar défaut : csvcsv ou xlsx.search, audience_id, unsubscribed, sort, order, match, key.conditionstringRéponse
Renvoie le fichier en pièce jointe : contacts.csv (text/csv; charset=utf-8) ou contacts.xlsx. Chaque ligne correspond à un contact, avec les colonnes suivantes :
| Colonne | Contenu |
|---|---|
email |
L’adresse e-mail. |
first_name, last_name |
Le prénom et le nom de famille. |
unsubscribed |
true ou false. |
audiences |
Les noms des listes du contact, séparés par ; . |
| Une colonne par champ personnalisé | La valeur de chaque champ personnalisé défini dans l’espace de travail ; la colonne porte le nom de sa clé. Les listes de valeurs sont jointes par ;. |
created_at, updated_at |
Horodatages ISO 8601. |
email,first_name,last_name,unsubscribed,audiences,company,plan,created_at,updated_at
ada@example.com,Ada,Lovelace,false,Newsletter,Analytical Engines,pro,2026-10-01T10:20:31.000000Z,2026-10-01T10:20:31.000000Z{
"error": "format must be csv or xlsx"
}{
"error": "Export is limited to 10000 contacts. Narrow your filters and try again."
}Supprimer un contact
Supprime définitivement un contact et toutes ses inscriptions aux listes.
/contacts/{id}Nécessite une clé API full. La suppression est irréversible. Pour ne plus envoyer d’e-mails à une personne tout en conservant sa fiche, mettez à jour le contact avec unsubscribed: true, ou ajoutez l’adresse à vos adresses bloquées. Déclenche subscriber.deleted pour chaque inscription, puis contact.deleted.
Paramètres de chemin
idstringobligatoirecon_…) ou son adresse e-mail, encodée pour l’URL.Réponse
objectstringcontact.idstringemailstringdeletedbooleantrue.{
"object": "contact",
"id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
"email": "alan@example.com",
"deleted": true
}{
"error": "Contact not found"
}