Documentation de l’API

Avec l’API de DIGO Email, votre site, votre boutique en ligne ou votre logiciel de gestion travaillent avec votre compte : ils inscrivent les contacts avec leur consentement, envoient des produits et des articles à utiliser dans vos e-mails, et enregistrent commandes et paniers pour mesurer ce que vend chaque campagne et déclencher les automatisations.

Avant de commencer

Dans ces cas, inutile d’écrire du code : la connexion est déjà prête.

• WordPress et WooCommerce : téléchargez le plugin depuis Intégrations. Il transmet à DIGO Email les inscriptions du checkout et des formulaires Contact Form 7, ainsi que les commandes, les produits, les articles du blog et les paniers.
• digo.sale : dans l’administration de la boutique, ouvrez Marketing → DIGO Email et collez la clé.
• Un formulaire d’inscription : chaque liste a le sien, à partager par un lien ou à intégrer à votre site, dans Listes et formulaires.
• ChatGPT et Claude : connectez votre assistant depuis Intégrations › ChatGPT et Claude. Il se connecte avec votre accord (OAuth), sans la clé API.

L’API sert à tout le reste : un site fait sur mesure, une autre plateforme d’e-commerce, un CRM, un logiciel de gestion ou une application avec son propre serveur.

Premiers pas

1. Dans le tableau de bord, ouvrez Intégrations. Dans Connecter un site, indiquez le nom et l’adresse du site et choisissez Site web comme plateforme.
2. Cliquez sur Connecter et créer la clé et copiez la clé qui s’affiche : elle commence par dge_ et nous ne l’affichons qu’une seule fois.
3. Testez la clé en demandant les informations de la connexion :

curl https://www.digo.email/api/v1/ping \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Accept: application/json"

{
  "store": "Boutique en ligne",
  "account": "Rossi SARL",
  "platform": "site",
  "can_send": true,
  "status": "active"
}

Dès la première requête réussie, le site apparaît comme Connecté dans le tableau de bord.

Authentification

Chaque requête transmet la clé du site dans l’en-tête Authorization, après le mot Bearer :

Authorization: Bearer dge_VOTRE_CLE

• Une clé par site. Vous pouvez connecter jusqu’à 20 sites, chacun avec sa clé. Produits, articles, commandes et paniers appartiennent au site qui les a envoyés ; contacts, listes, tags et champs appartiennent au compte et valent pour tous les sites.
• Gardez-la sur le serveur. Quiconque possède la clé peut inscrire des adresses et envoyer des commandes en votre nom : ne la mettez jamais dans le JavaScript de vos pages, dans une application installée sur des téléphones ni dans un dépôt public.
• Vous ne la voyez qu’une fois. Nous ne conservons qu’une empreinte chiffrée de la clé et le tableau de bord en affiche les six derniers caractères. Si vous la perdez, créez-en une nouvelle.
• Pour la changer, ouvrez Intégrations, puis Modifier ou changer de clé › Nouvelle clé : l’ancienne cesse aussitôt de fonctionner. Faites-le si vous pensez que quelqu’un l’a vue.
• Déconnecter le site désactive la clé et supprime les produits, articles et commandes reçus de ce site. Les contacts restent.

Requêtes et réponses

Toutes les adresses commencent ainsi :

https://www.digo.email/api/v1

• JSON. Envoyez les données en JSON avec Content-Type: application/json et demandez les réponses avec Accept: application/json. Les réponses sont toujours en JSON, en UTF-8. Utilisez toujours HTTPS.
• Vos propres identifiants. Produits, articles, commandes et paniers sont reconnus par votre id (texte, jusqu’à 64 caractères). Renvoyer le même id met à jour l’élément au lieu d’en créer un autre.
• Montants en unités de la devise, avec un point pour les décimales : 49.90, pas 4990. La devise est un code de trois lettres (EUR, CHF, CAD) ; à défaut, c’est celle du site définie dans Intégrations.
• Dates au format ISO 8601 avec le fuseau horaire : 2026-10-20T09:30:00+02:00.
• Messages. Le champ message des erreurs est rédigé pour des personnes, en italien, anglais, espagnol, français ou allemand selon l’en-tête Accept-Language ou la langue du compte. Dans votre code, décidez d’après le code HTTP et le champ error, qui ne changent pas.
• Nouveaux champs. Des champs peuvent s’ajouter aux réponses : ignorez ceux que vous ne connaissez pas.

Erreurs

Les codes 2xx indiquent que la requête a abouti. Dans les autres cas, le corps de la réponse explique ce qui s’est passé :

{
  "error": "account_inactive",
  "message": "Le compte DIGO Email n’est pas encore actif."
}

{
  "message": "Vous devez accepter la déclaration de consentement.",
  "errors": {
    "consent": ["Vous devez accepter la déclaration de consentement."]
  }
}

Limites

• Jusqu’à 300 requêtes par minute pour chaque site connecté, tous endpoints confondus.
• Pour POST /contacts, au maximum 60 inscriptions par minute et par site.
• Produits, articles et commandes passées voyagent par lots de 100 par requête.
• Les réponses indiquent la limite générale (X-RateLimit-Limit) et le nombre de requêtes restantes dans la minute (X-RateLimit-Remaining). Au-delà d’une limite, vous recevez 429 avec Retry-After.

Une requête qui a échoué à cause d’une erreur réseau, d’un 429 ou d’un 5xx peut être renvoyée sans crainte : commandes, produits, articles et paniers sont mis à jour par id, et un contact déjà inscrit n’est pas dupliqué. Les autres erreurs 4xx, en revanche, reviennent à l’identique tant que vous ne corrigez pas les données.

Liste des endpoints

Compte et paramètres

Ces endpoints lisent ce que vous avez préparé dans le tableau de bord : votre site s’en sert pour faire choisir listes, tags et champs à la personne qui le configure.

GET /ping

Vérifie la clé et le statut du compte. Appelez-le quand quelqu’un colle la clé dans les réglages de votre site et, de temps en temps, pour savoir si le compte accepte les inscriptions. La réponse est celle de Premiers pas.

GET /lists

Les listes du compte par ordre alphabétique, avec l’id à utiliser pour inscrire les contacts.

{
  "data": [
    { "id": 3, "name": "Clients", "double_opt_in": false },
    { "id": 5, "name": "Newsletter", "double_opt_in": true }
  ]
}

Avec double_opt_in à true, la personne qui s’inscrit reçoit un e-mail pour confirmer : elle devient inscrite, et reçoit les campagnes, seulement après avoir confirmé.

GET /tags

Les tags du compte par ordre alphabétique. Pour attribuer un tag à un contact, son nom suffit : les tags qui n’existent pas sont créés.

{
  "data": [
    { "id": 9, "name": "Paris" },
    { "id": 7, "name": "VIP" }
  ]
}

GET /fields

Les champs personnalisés des contacts, que vous créez dans Contacts › Champs personnalisés.

{
  "data": [
    { "key": "anniversaire", "label": "Anniversaire", "type": "date" },
    { "key": "entreprise", "label": "Entreprise", "type": "text" }
  ]
}

GET /forms

Les formulaires d’inscription des listes, avec tout ce qu’il faut pour les afficher dans le style de votre site. C’est ce qu’utilise le shortcode du plugin WordPress.

curl "https://www.digo.email/api/v1/forms?lang=fr" \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": 5,
      "name": "Newsletter",
      "title": "Inscrivez-vous à la newsletter",
      "action": "https://www.digo.email/f/k3Jd9QmZ2xTb7LpV4nWc8RyA1sGe6HuF",
      "locale": "fr",
      "consent_text": "J’accepte de recevoir des communications par e-mail de la part de Rossi SARL. Je peux me désabonner à tout moment.",
      "labels": { "email": "E-mail", "optional": "facultatif", "privacy": "Politique de confidentialité", "submit": "S’inscrire" },
      "privacy_url": "https://www.votresite.fr/confidentialite",
      "double_opt_in": true,
      "fields": [
        { "name": "first_name", "label": "Prénom", "type": "text", "required": false },
        { "name": "fields[anniversaire]", "label": "Anniversaire", "type": "date", "required": false }
      ],
      "script": "https://www.digo.email/js/digo-form.js?v=3",
      "can_send": true
    }
  ]
}

Le formulaire ne passe pas par votre serveur : le navigateur du visiteur l’envoie directement à l’adresse action, sans clé. Le consentement, le double opt-in et les protections contre les abus sont ceux des formulaires DIGO Email. Pour le construire :

• un <form method="post"> avec action comme destination ;
• le champ email et les champs de fields, chacun avec son name, obligatoires quand required vaut true ;
• une case consent à côté du texte consent_text et du lien vers privacy_url, ainsi qu’un champ caché consent_text contenant le même texte ;
• le script indiqué dans script. Sur les sites du compte (domaines d’envoi vérifiés et sites connectés), il envoie le formulaire sans quitter la page et y affiche la réponse ; ailleurs, ou sans le script, le visiteur voit la réponse sur une page de DIGO Email.

N’appelez aucun champ website : c’est le piège à robots, et un formulaire qui le remplit est ignoré. Sans le lien vers la politique de confidentialité dans les paramètres du compte, la réponse est 409 privacy_missing.

Contacts

POST /contacts

Inscrit une personne qui a accepté de recevoir vos e-mails : depuis un formulaire de votre site, au checkout ou lors de la création d’un compte. Sans consentement, rien n’est enregistré.

curl -X POST https://www.digo.email/api/v1/contacts \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "camille.martin@example.com",
    "first_name": "Camille",
    "last_name": "Martin",
    "list_ids": [5],
    "tags": ["Site web"],
    "fields": { "entreprise": "Martin Design", "anniversaire": "1990-04-18" },
    "consent": true,
    "consent_text": "Je veux recevoir la newsletter de Rossi SARL avec les nouveautés et les offres.",
    "source": "form",
    "form": "Pied de page",
    "language": "fr",
    "page": "https://www.votresite.fr/contact",
    "ip": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_6) AppleWebKit/605.1.15"
  }'

{ "status": "confirming" }

Les personnes déjà dans vos contacts

• Les listes et les tags sont ajoutés, jamais retirés.
• Le prénom et le nom restent ceux enregistrés ; les champs personnalisés ne sont remplis que s’ils sont vides, et la langue seulement si elle n’est pas déjà connue.
• Une personne déjà inscrite rejoint aussitôt les listes en double opt-in elles aussi, sans nouvelle confirmation.
• Une personne qui s’était désabonnée doit confirmer depuis sa propre boîte de réception, même pour les listes sans double opt-in : personne ne peut la réinscrire à sa place. Nous n’envoyons rien aux adresses qui ont rebondi ou signalé les e-mails comme spam.

Ce qui se passe ensuite

• Dès que le contact est inscrit, tout de suite ou lorsqu’il confirme, les automatisations S’inscrit à une liste et Reçoit un tag démarrent.
• Au-delà de la limite de contacts de votre compte, l’inscription est tout de même enregistrée, mais les campagnes et les automatisations s’arrêtent jusqu’à ce que vous achetiez d’autres contacts ou en supprimiez ; au double de la limite, les nouvelles inscriptions sont refusées avec 409 contact_limit.
• Dans la fiche du contact, vous retrouvez l’inscription avec le texte du consentement, le site, la page et le formulaire.

<?php
// La clé vient d’une variable d’environnement : ne l’écrivez pas dans le code.
$consentText = 'Je veux recevoir la newsletter de Rossi SARL avec les nouveautés et les offres.';

if (empty($_POST['consentement'])) {
    exit('Pour vous inscrire, cochez la case de consentement.');
}

$ch = curl_init('https://www.digo.email/api/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DIGO_EMAIL_KEY'),
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => trim($_POST['email'] ?? ''),
        'first_name' => trim($_POST['prenom'] ?? ''),
        'list_ids' => [5],
        'consent' => true,
        'consent_text' => $consentText, // le même texte que celui affiché à côté de la case
        'source' => 'form',
        'language' => 'fr',
        'page' => 'https://www.votresite.fr/contact',
        'ip' => $_SERVER['REMOTE_ADDR'],
        'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    ]),
]);
$body = json_decode((string) curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

$messages = [
    'subscribed' => 'Merci, vous êtes inscrit.',
    'confirming' => 'Presque terminé : ouvrez l’e-mail que nous vous avons envoyé et confirmez.',
    'limited' => 'Nous ne pouvons plus vous envoyer d’e-mail de confirmation aujourd’hui : réessayez demain.',
    'capped' => 'Nous ne pouvons plus vous envoyer d’e-mail de confirmation aujourd’hui : réessayez demain.',
];
if ($code === 200) {
    echo $messages[$body['status']] ?? $messages['subscribed'];
} else {
    error_log('DIGO Email: ' . ($body['message'] ?? 'HTTP ' . $code));
    echo 'Votre inscription n’a pas pu aboutir. Réessayez plus tard.';
}

const response = await fetch('https://www.digo.email/api/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DIGO_EMAIL_KEY}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    email: 'camille.martin@example.com',
    list_ids: [5],
    consent: true,
    consent_text: 'Je veux recevoir la newsletter de Rossi SARL avec les nouveautés et les offres.',
    source: 'checkout',
    language: 'fr',
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.message);
console.log(data.status); // subscribed, confirming, limited ou capped

Produits et articles

Les produits et les articles de blog que vous envoyez ici apparaissent dans l’éditeur d’e-mails, dans les blocs Produits et Articles : la personne qui rédige une campagne les choisit dans une liste, avec titre, image, prix et lien déjà prêts.

PUT /items

Crée ou met à jour jusqu’à 100 éléments par requête, reconnus par type et id. Envoyez-les tous la première fois, puis chaque fois que leur titre, leur prix, leur image ou leur disponibilité change.

curl -X PUT https://www.digo.email/api/v1/items \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "type": "product",
        "id": "1042",
        "title": "Tasse en céramique émaillée",
        "url": "https://www.votresite.fr/produits/tasse-emaillee",
        "image": "https://www.votresite.fr/media/tasse-emaillee.jpg",
        "excerpt": "Faite main, 350 ml, compatible lave-vaisselle.",
        "price": 24.00,
        "sale_price": 19.90,
        "available": true
      },
      {
        "type": "post",
        "id": "87",
        "title": "Comment choisir la bonne tasse",
        "url": "https://www.votresite.fr/blog/bonne-tasse",
        "image": "https://www.votresite.fr/media/blog-tasses.jpg",
        "excerpt": "Matières, contenance et entretien : un guide en cinq minutes.",
        "published_at": "2026-10-12T08:00:00+02:00"
      }
    ]
  }'

{ "saved": 2, "skipped": [] }

saved compte les éléments enregistrés ; skipped liste les id ignorés faute de nom ou d’adresse valide.

DELETE /items/{type}/{id}

Retire de la liste un produit que vous ne vendez plus ou un article qui n’est plus publié. Répond 204, sans contenu, même si l’élément n’existait pas. Les e-mails déjà préparés qui le contiennent ne changent pas.

curl -X DELETE https://www.digo.email/api/v1/items/product/1042 \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Accept: application/json"

Commandes

Les commandes servent à mesurer ce que vend chaque campagne, à déclencher les automatisations Fait un achat dans la boutique et à fermer les paniers abandonnés. Les acheteurs ne deviennent pas des contacts : nous ne gardons une commande que si l’acheteur fait déjà partie de vos contacts ou s’il arrive par le lien d’une campagne (voir Ventes des campagnes). Les autres sont écartées.

POST /orders

Enregistre une commande ou met à jour son statut. Envoyez-la à sa création, puis à chaque changement (paiement, remboursement, annulation), toujours avec le même id.

curl -X POST https://www.digo.email/api/v1/orders \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "5531",
    "number": "#5531",
    "email": "camille.martin@example.com",
    "status": "paid",
    "total": 43.80,
    "refunded": 0,
    "currency": "EUR",
    "created_at": "2026-10-20T10:15:00+02:00",
    "click_id": "184467.9f1c2ab07d3e4f51",
    "items": [
      { "id": "1042", "name": "Tasse en céramique émaillée", "quantity": 2, "total": 39.80 }
    ]
  }'

{ "attributed": true }

attributed vaut true quand la commande compte pour une campagne. Une commande qui ne concerne ni un contact ni une campagne n’est pas conservée, et la réponse est {"attributed": false, "stored": false}.

• Quand une commande passe à paid pour la première fois et que l’acheteur est un contact, les automatisations Fait un achat dans la boutique démarrent.
• Une commande pending ou paid ferme les paniers ouverts de l’acheteur : les e-mails de panier abandonné ne partent plus.
• Les rapports comptent les commandes payées, moins les remboursements. Les commandes en attente et annulées ne comptent pas.

POST /orders/history

Importe les commandes passées, jusqu’à 100 par requête, dans orders et avec les mêmes champs que POST /orders. Les mêmes règles s’appliquent, mais ces commandes décrivent ce qui s’est déjà produit : elles ne déclenchent pas d’automatisations et ne ferment pas de paniers. Vous pouvez les renvoyer : elles mettent à jour les mêmes commandes. Un e-mail non valide ne correspond simplement à aucun contact.

curl -X POST https://www.digo.email/api/v1/orders/history \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "orders": [
      { "id": "4870", "email": "camille.martin@example.com", "status": "paid", "total": 24.00, "created_at": "2026-03-02T17:40:00+01:00" },
      { "id": "4871", "email": "lucas.bernard@example.com", "status": "refunded", "total": 58.50, "refunded": 58.50, "created_at": "2026-03-03T09:12:00+01:00" }
    ]
  }'

{ "received": 2, "stored": 1 }

received compte les commandes reçues, stored celles conservées parce qu’elles concernent vos contacts ou proviennent d’une campagne.

Paniers

Avec les paniers, vous pouvez rappeler aux clients ce qu’ils ont laissé dans votre boutique, grâce à l’automatisation Abandonne son panier. Dans les e-mails, les variables {{carrello_link}}, {{carrello_totale}} et {{carrello_prodotti}} affichent le lien pour reprendre le panier, le total et les produits.

PUT /carts

Enregistre le panier d’un client dont vous connaissez l’e-mail, parce qu’il s’est connecté ou l’a saisi au checkout. Renvoyez-le à chaque modification, toujours avec le même id. Nous ne gardons que les paniers des personnes qui font déjà partie de vos contacts : personne ne devient contact en remplissant un panier.

curl -X PUT https://www.digo.email/api/v1/carts \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "c-8f2a1c",
    "email": "camille.martin@example.com",
    "total": 39.80,
    "currency": "EUR",
    "url": "https://www.votresite.fr/panier?reprendre=8f2a1c",
    "items": [
      { "id": "1042", "name": "Tasse en céramique émaillée", "quantity": 2, "total": 39.80, "image": "https://www.votresite.fr/media/tasse-emaillee.jpg" }
    ]
  }'

{ "saved": true }

Si l’e-mail n’appartient pas à l’un de vos contacts, la réponse est {"saved": false} et un éventuel panier enregistré auparavant avec le même id est retiré.

DELETE /carts/{id}

Ferme un panier que le client a vidé. Répond 204, sans contenu. Inutile après un achat : la commande ferme déjà les paniers de l’acheteur.

curl -X DELETE https://www.digo.email/api/v1/carts/c-8f2a1c \
  -H "Authorization: Bearer dge_VOTRE_CLE" \
  -H "Accept: application/json"

Ventes des campagnes

Pour vous dire ce que vend chaque campagne, DIGO Email relie les commandes aux clics dans les e-mails :

1. Quand quelqu’un clique dans l’e-mail sur un lien qui mène à votre site, nous ajoutons à l’adresse le paramètre digo_c, par exemple https://www.votresite.fr/produits/tasse-emaillee?digo_c=184467.9f1c2ab07d3e4f51. Cela vaut pour l’adresse du site définie dans Intégrations et pour ses sous-domaines.
2. Si le visiteur a accepté les cookies marketing, votre site enregistre la valeur dans le cookie digo_c pendant 7 jours. Un clic plus récent remplace le précédent.
3. Quand le client achète, vous envoyez la valeur du cookie comme click_id avec la commande.

La commande compte pour la campagne si elle arrive dans les 7 jours suivant le dernier clic sur cet e-mail. Si le client a cliqué sur plusieurs e-mails, c’est le dernier qui compte.

<script>
(function () {
  var click = new URLSearchParams(location.search).get('digo_c');
  if (!/^\d{1,19}\.[a-f0-9]{16}$/.test(click || '')) return;
  if (!consentementMarketing()) return; // la vérification de votre bandeau cookies
  document.cookie = 'digo_c=' + click + '; path=/; max-age=604800; SameSite=Lax; Secure';
})();
</script>

$order['click_id'] = $_COOKIE['digo_c'] ?? null;

Le lien ne fonctionne que si la mesure des clics est activée, dans Paramètres › Entreprise › Mesurer les ouvertures et les clics : sans elle, les liens des e-mails mènent directement au site et ne portent pas digo_c.

Bonnes pratiques

• Appelez l’API depuis votre serveur, jamais depuis le navigateur : la clé ne doit pas en sortir.
• Ne faites pas attendre vos clients. Au checkout, mettez en file d’attente inscriptions, commandes et paniers et envoyez-les juste après : si DIGO Email est lent ou injoignable, l’achat ne doit pas être bloqué.
• Réessayez calmement après une erreur réseau, un 429 ou un 5xx, en attendant un peu plus à chaque tentative. Les requêtes en erreur 4xx d’un autre type doivent être corrigées, pas répétées.
• Demandez le consentement avec une case à cocher, non cochée d’avance, et envoyez dans consent_text exactement le texte que la personne a lu.
• Envoyez la langue de la personne qui s’inscrit avec language : e-mails de confirmation, campagnes et pages de désabonnement la suivront.
• Tenez votre catalogue à jour : envoyez les produits quand ils changent et retirez-les quand ils ne sont plus en vente.
• Testez avec une liste de test et vos propres adresses. Les inscriptions de test sont de vrais contacts : elles comptent dans votre limite et, en double opt-in, reçoivent de vrais e-mails. À la fin, supprimez-les depuis le tableau de bord.

Assistance

Pour toute question sur l’API, écrivez à info@digo.email. Indiquez le nom du site connecté, l’endpoint et la réponse reçue : jamais la clé.