Aller au contenu
Docs

Gérez les profils de contacts et les champs personnalisés, en masse ou un par un.

URL de basehttps://api.emailit.com/v2AuthentificationErreursLimites de débit

Créer un contact

Crée un contact et l’inscrit éventuellement à des listes de contacts.

POST/contacts

Né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

emailstringobligatoire
L’adresse e-mail du contact.
first_namestring
Le prénom.
last_namestring
Le nom de famille.
custom_fieldsobject

Valeurs 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[]
ID des listes (aud_…) auxquelles inscrire le contact. Les ID qui n’existent pas dans l’espace de travail sont ignorés.
unsubscribedbooleanpar défaut : false

true 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éé.

POST/contacts
Terminal
curl -X POST https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines", "plan": "pro" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"]
  }'
JSON
{
  "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"
}

Récupérer un contact

Récupère un contact avec ses champs personnalisés et ses inscriptions aux listes de contacts.

GET/contacts/{id}

Nécessite une clé API full.

Paramètres de chemin

idstringobligatoire
L’ID du contact (con_…) ou son adresse e-mail, encodée pour l’URL.

Réponse

Renvoie l’objet contact.

objectstring
Toujours contact.
idstring
L’ID du contact.
emailstring
L’adresse e-mail, en minuscules.
first_namestring | null
Le prénom.
last_namestring | null
Le nom de famille.
custom_fieldsobject
Valeurs des champs personnalisés par clé. {} s’il n’y en a aucun.
unsubscribedboolean
true 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_atstring
Date de création du contact.
updated_atstring
Date de la dernière modification du contact.
GET/contacts/{id}
Terminal
curl https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "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"
}

Mettre à jour un contact

Met à jour un contact. Seuls les champs que vous envoyez sont modifiés.

POST/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

idstringobligatoire
L’ID du contact (con_…) ou son adresse e-mail, encodée pour l’URL.

Paramètres du corps

emailstring
Une nouvelle adresse e-mail. Ne doit pas appartenir à un autre contact.
first_namestring
Le prénom.
last_namestring
Le nom de famille.
custom_fieldsobject
Valeurs des champs personnalisés par clé. Remplacent tous les champs personnalisés du contact : incluez ceux que vous voulez conserver.
unsubscribedboolean
true 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.

POST/contacts/{id}
Terminal
curl -X POST https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
Terminal
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"]
  }'
JSON
{
  "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"
}

Lister les contacts

Renvoie une page de contacts, du plus récent au plus ancien.

GET/contacts

Né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 : 1
La page à renvoyer.
limitintegerpar défaut : 10
Nombre de contacts par page, de 1 à 100.
audience_idstring
Uniquement les contacts de cette liste (aud_…).
unsubscribedboolean
true ou false. Uniquement les contacts ayant ce statut de désinscription.
sortstringpar défaut : created_at
email, first_name, last_name, name, audiences, created_at ou updated_at.
orderstringpar défaut : desc
asc ou desc. Sur cet endpoint, order est le sens du tri, pas la clé de tri.
matchstringpar défaut : all
all 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[]
Les contacts de cette page, chacun avec audiences sous la forme id, name et subscribed. Consultez Récupérer un contact.
total_recordsinteger
Le nombre de contacts correspondants, toutes pages confondues.
next_page_urlstring | null
Chemin de la page suivante avec vos filtres, ou null. Consultez Pagination.
previous_page_urlstring | null
Chemin de la page précédente, ou null.
GET/contacts
Terminal
curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
Terminal
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"
JSON
{
  "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.

POST/contacts/bulk

Né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

actionstringobligatoire
delete, add_to_audience, remove_from_audience, unsubscribe ou resubscribe.
idsstring[]obligatoire
ID de contacts (con_…), de 1 à 100. Les adresses e-mail ne sont pas acceptées ici. Les doublons sont ignorés.
audience_idstring
L’ID de la liste. Obligatoire pour add_to_audience et remove_from_audience.

Réponse

objectstring
Toujours contact_bulk.
actionstring
L’action exécutée.
processedinteger
Nombre de contacts traités.
idsstring[]
Les ID des contacts traités.
POST/contacts/bulk
Terminal
curl -X POST https://api.emailit.com/v2/contacts/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}'
JSON
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}

Exporter des contacts

Télécharge les contacts correspondants dans un fichier CSV ou XLSX.

GET/contacts/export

Né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 : csv
csv ou xlsx.
search, audience_id, unsubscribed, sort, order, match, key.conditionstring
Les mêmes paramètres que Lister les contacts.

Ré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.
GET/contacts/export
Terminal
curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv
Text
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

Supprimer un contact

Supprime définitivement un contact et toutes ses inscriptions aux listes.

DELETE/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

idstringobligatoire
L’ID du contact (con_…) ou son adresse e-mail, encodée pour l’URL.

Réponse

objectstring
Toujours contact.
idstring
L’ID du contact supprimé.
emailstring
L’adresse e-mail du contact.
deletedboolean
Toujours true.
DELETE/contacts/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/contacts/con_4Kt4ZXloQR8WGcMsYx8PFCUjokM \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "contact",
  "id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
  "email": "alan@example.com",
  "deleted": true
}

Cette page vous a-t-elle été utile ?

Merci pour votre retour.

Merci, nous lisons chaque message.