Documentazione API

Con l’API di DIGO Email il tuo sito, il tuo negozio online o il tuo gestionale lavorano insieme al tuo account: iscrivono i contatti con il loro consenso, inviano prodotti e articoli da mettere nelle email, registrano ordini e carrelli per misurare quanto vende ogni campagna e far partire le automazioni.

Prima di iniziare

In questi casi non serve scrivere codice, perché il collegamento è già pronto:

• WordPress e WooCommerce: scarica il plugin da Integrazioni. Porta in DIGO Email le iscrizioni dal checkout e dai moduli Contact Form 7, gli ordini, i prodotti, gli articoli del blog e i carrelli.
• digo.sale: nell’amministrazione del negozio apri Marketing → DIGO Email e incolla la chiave.
• Un modulo di iscrizione: ogni lista ha il suo, da condividere con un link o da incorporare nel sito, in Liste e moduli.
• ChatGPT e Claude: collega il tuo assistente da Integrazioni › ChatGPT e Claude. Accede con il tuo consenso (OAuth), senza la chiave API.

L’API serve per tutto il resto: un sito fatto su misura, un’altra piattaforma di e-commerce, un CRM, un gestionale o un’app con il suo server.

Primi passi

1. Nel pannello apri Integrazioni. In Collega un sito scrivi il nome e l’indirizzo del sito e scegli Sito web come piattaforma.
2. Premi Collega e crea la chiave e copia la chiave che compare: inizia con dge_ e te la mostriamo una sola volta.
3. Prova la chiave chiedendo i dati del collegamento:

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

{
  "store": "Negozio online",
  "account": "Rossi S.r.l.",
  "platform": "site",
  "can_send": true,
  "status": "active"
}

Dalla prima richiesta riuscita il sito risulta Collegato nel pannello.

Autenticazione

Ogni richiesta porta la chiave del sito nell’intestazione Authorization, dopo la parola Bearer:

Authorization: Bearer dge_LA_TUA_CHIAVE

• Una chiave per sito. Puoi collegare fino a 20 siti, ognuno con la sua chiave. Prodotti, articoli, ordini e carrelli appartengono al sito che li ha inviati; contatti, liste, tag e campi sono dell’account e valgono per tutti i siti.
• Tienila sul server. Chi ha la chiave può iscrivere indirizzi e inviare ordini a nome tuo: non metterla nel JavaScript delle pagine, in un’app installata sui telefoni o in un repository pubblico.
• La vedi una volta sola. Conserviamo solo un’impronta cifrata della chiave e nel pannello ne mostriamo gli ultimi sei caratteri. Se la perdi, creane una nuova.
• Per cambiarla apri Integrazioni, poi Modifica o cambia chiave › Nuova chiave: quella di prima smette subito di funzionare. Fallo se pensi che qualcuno l’abbia vista.
• Scollegare il sito disattiva la chiave e cancella prodotti, articoli e ordini ricevuti da quel sito. I contatti restano.

Richieste e risposte

Tutti gli indirizzi iniziano così:

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

• JSON. Invia i dati in JSON con Content-Type: application/json e chiedi le risposte con Accept: application/json. Le risposte sono sempre in JSON, in UTF-8. Usa sempre HTTPS.
• I tuoi identificativi. Prodotti, articoli, ordini e carrelli si riconoscono dal tuo id (testo, fino a 64 caratteri). Inviare di nuovo lo stesso id aggiorna l’elemento invece di crearne un altro.
• Importi in unità della valuta, con il punto per i decimali: 49.90, non 4990. La valuta è un codice di tre lettere (EUR, CHF, USD); se manca vale quella del sito impostata in Integrazioni.
• Date in formato ISO 8601 con il fuso orario: 2026-10-20T09:30:00+02:00.
• Messaggi. Il campo message degli errori è scritto per le persone, in italiano, inglese, spagnolo, francese o tedesco secondo l’intestazione Accept-Language o la lingua dell’account. Nel codice decidi in base al codice HTTP e al campo error, che non cambiano.
• Campi nuovi. Alle risposte possono aggiungersi campi: ignora quelli che non conosci.

Errori

I codici 2xx indicano che la richiesta è andata a buon fine. Negli altri casi il corpo della risposta spiega cosa è successo:

{
  "error": "account_inactive",
  "message": "L’account DIGO Email non è ancora attivo."
}

{
  "message": "Devi accettare la dichiarazione di consenso.",
  "errors": {
    "consent": ["Devi accettare la dichiarazione di consenso."]
  }
}

Limiti

• Fino a 300 richieste al minuto per ogni sito collegato, contando tutti gli endpoint.
• Per POST /contacts al massimo 60 iscrizioni al minuto per sito.
• Prodotti, articoli e ordini passati viaggiano a gruppi di 100 per richiesta.
• Le risposte indicano il limite generale (X-RateLimit-Limit) e quante richieste restano nel minuto (X-RateLimit-Remaining). Oltre un limite ricevi 429 con Retry-After.

Una richiesta fallita per un errore di rete, un 429 o un 5xx si può ripetere senza timori: ordini, prodotti, articoli e carrelli si aggiornano per id e un contatto già iscritto non viene duplicato. Gli altri errori 4xx invece si ripetono uguali finché non correggi i dati.

Elenco degli endpoint

Account e impostazioni

Questi endpoint leggono quello che hai preparato nel pannello: servono al tuo sito per far scegliere liste, tag e campi a chi lo configura.

GET /ping

Controlla la chiave e lo stato dell’account. Chiamalo quando qualcuno incolla la chiave nelle impostazioni del tuo sito e, ogni tanto, per sapere se l’account accetta iscrizioni. La risposta è quella di Primi passi.

GET /lists

Le liste dell’account in ordine alfabetico, con l’id da usare per iscrivere i contatti.

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

Con double_opt_in a true chi si iscrive riceve un’email per confermare: diventa iscritto, e riceve le campagne, solo dopo aver confermato.

GET /tags

I tag dell’account in ordine alfabetico. Per assegnare un tag a un contatto basta il suo nome: quelli che non esistono vengono creati.

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

GET /fields

I campi personalizzati dei contatti, che crei in Contatti › Campi personalizzati.

{
  "data": [
    { "key": "azienda", "label": "Azienda", "type": "text" },
    { "key": "compleanno", "label": "Compleanno", "type": "date" }
  ]
}

GET /forms

I moduli di iscrizione delle liste, con tutto quello che serve per mostrarli nello stile del tuo sito. È quello che usa lo shortcode del plugin per WordPress.

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

{
  "data": [
    {
      "id": 5,
      "name": "Newsletter",
      "title": "Iscriviti alla newsletter",
      "action": "https://www.digo.email/f/k3Jd9QmZ2xTb7LpV4nWc8RyA1sGe6HuF",
      "locale": "it",
      "consent_text": "Acconsento a ricevere comunicazioni via email da Rossi S.r.l. Posso annullare l’iscrizione in qualsiasi momento.",
      "labels": { "email": "Email", "optional": "facoltativo", "privacy": "Informativa privacy", "submit": "Iscriviti" },
      "privacy_url": "https://www.tuosito.it/privacy",
      "double_opt_in": true,
      "fields": [
        { "name": "first_name", "label": "Nome", "type": "text", "required": false },
        { "name": "fields[compleanno]", "label": "Compleanno", "type": "date", "required": false }
      ],
      "script": "https://www.digo.email/js/digo-form.js?v=3",
      "can_send": true
    }
  ]
}

Il modulo non passa dal tuo server: il browser del visitatore lo invia direttamente all’indirizzo action, senza chiave. Consenso, doppio opt-in e protezioni contro gli abusi sono quelli dei moduli di DIGO Email. Per costruirlo:

• un <form method="post"> con action come destinazione;
• il campo email e i campi di fields, ognuno con il suo name, obbligatori quando required è true;
• una casella consent con accanto il testo consent_text e il link a privacy_url, più un campo nascosto consent_text con lo stesso testo;
• lo script indicato in script. Sui siti dell’account (i domini di invio verificati e i siti collegati) invia il modulo senza lasciare la pagina e mostra lì la risposta; altrove, o senza script, il visitatore vede la risposta su una pagina di DIGO Email.

Non chiamare website nessun campo: è la trappola per i programmi automatici e un modulo che lo compila viene ignorato. Senza il link all’informativa privacy nelle impostazioni dell’account la risposta è 409 privacy_missing.

Contatti

POST /contacts

Iscrive una persona che ha dato il consenso a ricevere le tue email: da un modulo del sito, dal checkout o dalla registrazione. Senza consenso non viene salvato nulla.

curl -X POST https://www.digo.email/api/v1/contacts \
  -H "Authorization: Bearer dge_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "giulia.bianchi@example.com",
    "first_name": "Giulia",
    "last_name": "Bianchi",
    "list_ids": [5],
    "tags": ["Sito web"],
    "fields": { "azienda": "Bianchi Design", "compleanno": "1990-04-18" },
    "consent": true,
    "consent_text": "Voglio ricevere la newsletter di Rossi S.r.l. con novità e offerte.",
    "source": "form",
    "form": "Piè di pagina",
    "language": "it",
    "page": "https://www.tuosito.it/contatti",
    "ip": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_6) AppleWebKit/605.1.15"
  }'

{ "status": "confirming" }

Chi è già tra i tuoi contatti

• Liste e tag vengono aggiunti, mai tolti.
• Nome e cognome restano quelli che ha; i campi personalizzati vengono riempiti solo se sono vuoti, e la lingua solo se non ne ha una.
• Chi è già iscritto entra subito anche nelle liste con doppio opt-in, senza un’altra conferma.
• Chi si era disiscritto deve confermare dalla sua casella, anche per le liste senza doppio opt-in: nessuno può iscriverlo di nuovo al posto suo. Agli indirizzi che hanno rimbalzato o segnalato le email come spam non inviamo nulla.

Cosa succede dopo

• Appena il contatto è iscritto, subito o quando conferma, partono le automazioni Si iscrive a una lista e Riceve un tag.
• Oltre il limite di contatti del tuo account l’iscrizione viene salvata lo stesso, ma campagne e automazioni si fermano finché non acquisti altri contatti o ne rimuovi; al doppio del limite le nuove iscrizioni vengono rifiutate con 409 contact_limit.
• Nella scheda del contatto trovi l’iscrizione con il testo del consenso, il sito, la pagina e il modulo.

<?php
// La chiave arriva da una variabile d’ambiente: non scriverla nel codice.
$consentText = 'Voglio ricevere la newsletter di Rossi S.r.l. con novità e offerte.';

if (empty($_POST['consenso'])) {
    exit('Per iscriverti spunta la casella del consenso.');
}

$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['nome'] ?? ''),
        'list_ids' => [5],
        'consent' => true,
        'consent_text' => $consentText, // lo stesso testo mostrato accanto alla casella
        'source' => 'form',
        'language' => 'it',
        'page' => 'https://www.tuosito.it/contatti',
        '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' => 'Grazie, sei iscritto.',
    'confirming' => 'Quasi fatto: apri l’email che ti abbiamo inviato e conferma.',
    'limited' => 'Oggi non possiamo inviarti altre email di conferma: riprova domani.',
    'capped' => 'Oggi non possiamo inviarti altre email di conferma: riprova domani.',
];
if ($code === 200) {
    echo $messages[$body['status']] ?? $messages['subscribed'];
} else {
    error_log('DIGO Email: ' . ($body['message'] ?? 'HTTP ' . $code));
    echo 'Non è stato possibile completare l’iscrizione. Riprova più tardi.';
}

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: 'giulia.bianchi@example.com',
    list_ids: [5],
    consent: true,
    consent_text: 'Voglio ricevere la newsletter di Rossi S.r.l. con novità e offerte.',
    source: 'checkout',
    language: 'it',
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.message);
console.log(data.status); // subscribed, confirming, limited o capped

Prodotti e articoli

I prodotti e gli articoli del blog che invii qui compaiono nell’editor delle email, nei blocchi Prodotti e Articoli: chi scrive una campagna li sceglie da un elenco, con titolo, immagine, prezzo e link già pronti.

PUT /items

Crea o aggiorna fino a 100 elementi per richiesta, riconosciuti da type e id. Inviali tutti la prima volta, poi ogni volta che cambiano titolo, prezzo, immagine o disponibilità.

curl -X PUT https://www.digo.email/api/v1/items \
  -H "Authorization: Bearer dge_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "type": "product",
        "id": "1042",
        "title": "Tazza in ceramica smaltata",
        "url": "https://www.tuosito.it/prodotti/tazza-smaltata",
        "image": "https://www.tuosito.it/media/tazza-smaltata.jpg",
        "excerpt": "Fatta a mano, 350 ml, adatta alla lavastoviglie.",
        "price": 24.00,
        "sale_price": 19.90,
        "available": true
      },
      {
        "type": "post",
        "id": "87",
        "title": "Come scegliere la tazza giusta",
        "url": "https://www.tuosito.it/blog/tazza-giusta",
        "image": "https://www.tuosito.it/media/blog-tazze.jpg",
        "excerpt": "Materiali, capienza e cura: una guida in cinque minuti.",
        "published_at": "2026-10-12T08:00:00+02:00"
      }
    ]
  }'

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

saved conta gli elementi salvati; skipped elenca gli id saltati perché senza nome o senza un indirizzo valido.

DELETE /items/{type}/{id}

Toglie dall’elenco un prodotto che non vendi più o un articolo non più pubblicato. Risponde 204, senza contenuto, anche se l’elemento non c’era. Le email già preparate che lo contengono non cambiano.

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

Ordini

Gli ordini servono a misurare quanto vende ogni campagna, a far partire le automazioni Fa un acquisto nel negozio e a chiudere i carrelli abbandonati. Gli acquirenti non diventano contatti: teniamo un ordine solo se chi compra è già tra i tuoi contatti o se arriva dal link di una campagna (vedi Vendite dalle campagne). Gli altri vengono scartati.

POST /orders

Registra un ordine o ne aggiorna lo stato. Invialo quando viene creato e di nuovo a ogni cambiamento (pagamento, rimborso, annullamento), sempre con lo stesso id.

curl -X POST https://www.digo.email/api/v1/orders \
  -H "Authorization: Bearer dge_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "5531",
    "number": "#5531",
    "email": "giulia.bianchi@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": "Tazza in ceramica smaltata", "quantity": 2, "total": 39.80 }
    ]
  }'

{ "attributed": true }

attributed è true quando l’ordine conta per una campagna. Un ordine che non riguarda né un contatto né una campagna non viene tenuto e la risposta è {"attributed": false, "stored": false}.

• Quando un ordine diventa paid per la prima volta e chi compra è un contatto, partono le automazioni Fa un acquisto nel negozio.
• Un ordine pending o paid chiude i carrelli aperti di chi compra: le email di carrello abbandonato non partono più.
• Nei report contano gli ordini pagati, meno i rimborsi. Quelli in attesa e quelli annullati non contano.

POST /orders/history

Importa gli ordini passati, fino a 100 per richiesta, dentro orders e con gli stessi campi di POST /orders. Valgono le stesse regole, ma questi ordini descrivono ciò che è già successo: non fanno partire automazioni e non chiudono carrelli. Puoi inviarli di nuovo: aggiornano gli stessi ordini. Un’email non valida semplicemente non corrisponde a nessun contatto.

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

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

received conta gli ordini ricevuti, stored quelli tenuti perché di tuoi contatti o arrivati da una campagna.

Carrelli

Con i carrelli puoi ricordare ai clienti cosa hanno lasciato nel negozio, con l’automazione Abbandona il carrello. Nelle email i segnaposto {{carrello_link}}, {{carrello_totale}} e {{carrello_prodotti}} mostrano il link per riprendere il carrello, il totale e i prodotti.

PUT /carts

Salva il carrello di un cliente di cui conosci l’email, perché ha fatto l’accesso o l’ha scritta al checkout. Invialo di nuovo a ogni modifica, sempre con lo stesso id. Teniamo solo i carrelli di chi è già tra i tuoi contatti: nessuno diventa contatto riempiendo un carrello.

curl -X PUT https://www.digo.email/api/v1/carts \
  -H "Authorization: Bearer dge_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "c-8f2a1c",
    "email": "giulia.bianchi@example.com",
    "total": 39.80,
    "currency": "EUR",
    "url": "https://www.tuosito.it/carrello?riprendi=8f2a1c",
    "items": [
      { "id": "1042", "name": "Tazza in ceramica smaltata", "quantity": 2, "total": 39.80, "image": "https://www.tuosito.it/media/tazza-smaltata.jpg" }
    ]
  }'

{ "saved": true }

Se l’email non è di un tuo contatto la risposta è {"saved": false} e un eventuale carrello salvato prima con lo stesso id viene tolto.

DELETE /carts/{id}

Chiude un carrello che il cliente ha svuotato. Risponde 204, senza contenuto. Dopo un acquisto non serve: l’ordine chiude già i carrelli di chi compra.

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

Vendite dalle campagne

Per dirti quanto vende ogni campagna, DIGO Email collega gli ordini ai clic nelle email:

1. Quando qualcuno clicca nell’email un link che porta al tuo sito, aggiungiamo all’indirizzo il parametro digo_c, per esempio https://www.tuosito.it/prodotti/tazza-smaltata?digo_c=184467.9f1c2ab07d3e4f51. Vale per l’indirizzo del sito impostato in Integrazioni e per i suoi sottodomini.
2. Il tuo sito, se il visitatore ha accettato i cookie di marketing, salva il valore nel cookie digo_c per 7 giorni. Un clic più recente sostituisce il precedente.
3. Quando il cliente compra, invii il valore del cookie come click_id insieme all’ordine.

L’ordine conta per la campagna se arriva entro 7 giorni dall’ultimo clic su quell’email. Se il cliente ha cliccato più email, vale l’ultima.

<script>
(function () {
  var click = new URLSearchParams(location.search).get('digo_c');
  if (!/^\d{1,19}\.[a-f0-9]{16}$/.test(click || '')) return;
  if (!haAccettatoMarketing()) return; // la verifica del tuo banner dei cookie
  document.cookie = 'digo_c=' + click + '; path=/; max-age=604800; SameSite=Lax; Secure';
})();
</script>

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

Il collegamento funziona solo con la misurazione dei clic attiva, in Impostazioni › Azienda › Misura aperture e clic: senza, i link delle email portano direttamente al sito e non hanno digo_c.

Buone pratiche

• Chiama l’API dal tuo server, mai dal browser: la chiave non deve uscirne.
• Non far aspettare i clienti. Al checkout metti in coda iscrizioni, ordini e carrelli e inviali subito dopo: se DIGO Email è lento o irraggiungibile, l’acquisto non deve bloccarsi.
• Riprova con calma dopo un errore di rete, un 429 o un 5xx, aspettando un po’ di più a ogni tentativo. Le richieste con altri errori 4xx vanno corrette, non ripetute.
• Chiedi il consenso con una casella da spuntare, non già spuntata, e invia in consent_text esattamente il testo che la persona ha letto.
• Invia la lingua di chi si iscrive con language: email di conferma, campagne e pagine di disiscrizione la seguiranno.
• Tieni aggiornato il catalogo: invia i prodotti quando cambiano e toglili quando non sono più in vendita.
• Prova con una lista di test e indirizzi tuoi. Le iscrizioni di prova sono contatti veri: contano nel limite e, con il doppio opt-in, ricevono email vere. Alla fine cancellali dal pannello.

Assistenza

Per domande sull’API scrivi a info@digo.email. Indica il nome del sito collegato, l’endpoint e la risposta ricevuta: mai la chiave.