Documentación de la API

Con la API de DIGO Email, tu sitio web, tu tienda online o tu sistema de gestión trabajan junto a tu cuenta: suscriben a los contactos con su consentimiento, envían productos y artículos para usar en tus emails y registran pedidos y carritos para medir cuánto vende cada campaña y poner en marcha las automatizaciones.

Antes de empezar

En estos casos no hace falta escribir código, porque la conexión ya está lista:

• WordPress y WooCommerce: descarga el plugin desde Integraciones. Lleva a DIGO Email las suscripciones del checkout y de los formularios de Contact Form 7, los pedidos, los productos, los artículos del blog y los carritos.
• digo.sale: en la administración de la tienda abre Marketing → DIGO Email y pega la clave.
• Un formulario de suscripción: cada lista tiene el suyo, para compartirlo con un enlace o insertarlo en tu sitio, en Listas y formularios.
• ChatGPT y Claude: conecta tu asistente desde Integraciones › ChatGPT y Claude. Accede con tu consentimiento (OAuth), sin la clave API.

La API sirve para todo lo demás: un sitio web hecho a medida, otra plataforma de e-commerce, un CRM, un sistema de gestión o una app con su propio servidor.

Primeros pasos

1. En el panel abre Integraciones. En Conectar un sitio escribe el nombre y la dirección del sitio y elige Sitio web como plataforma.
2. Pulsa Conectar y crear la clave y copia la clave que aparece: empieza por dge_ y solo te la mostramos una vez.
3. Prueba la clave pidiendo los datos de la conexión:

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

{
  "store": "Tienda online",
  "account": "Rossi S.L.",
  "platform": "site",
  "can_send": true,
  "status": "active"
}

Desde la primera solicitud correcta, el sitio aparece como Conectado en el panel.

Autenticación

Cada solicitud lleva la clave del sitio en la cabecera Authorization, después de la palabra Bearer:

Authorization: Bearer dge_TU_CLAVE

• Una clave por sitio. Puedes conectar hasta 20 sitios, cada uno con su clave. Productos, artículos, pedidos y carritos pertenecen al sitio que los envió; contactos, listas, etiquetas y campos son de la cuenta y valen para todos los sitios.
• Guárdala en el servidor. Quien tenga la clave puede suscribir direcciones y enviar pedidos en tu nombre: nunca la pongas en el JavaScript de tus páginas, en una app instalada en los móviles ni en un repositorio público.
• Solo la ves una vez. Guardamos únicamente una huella cifrada de la clave y en el panel mostramos sus últimos seis caracteres. Si la pierdes, crea una nueva.
• Para cambiarla abre Integraciones y luego Editar o cambiar clave › Clave nueva: la anterior deja de funcionar al instante. Hazlo si crees que alguien la ha visto.
• Desconectar el sitio desactiva la clave y borra los productos, artículos y pedidos recibidos de ese sitio. Los contactos se quedan.

Solicitudes y respuestas

Todas las direcciones empiezan así:

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

• JSON. Envía los datos en JSON con Content-Type: application/json y pide las respuestas con Accept: application/json. Las respuestas siempre son JSON, en UTF-8. Usa siempre HTTPS.
• Tus propios identificadores. Productos, artículos, pedidos y carritos se reconocen por tu id (texto, hasta 64 caracteres). Enviar de nuevo el mismo id actualiza el elemento en lugar de crear otro.
• Importes en unidades de la moneda, con punto para los decimales: 49.90, no 4990. La moneda es un código de tres letras (EUR, MXN, USD); si falta, vale la del sitio configurada en Integraciones.
• Fechas en formato ISO 8601 con la zona horaria: 2026-10-20T09:30:00+02:00.
• Mensajes. El campo message de los errores está escrito para personas, en italiano, inglés, español, francés o alemán según la cabecera Accept-Language o el idioma de la cuenta. En tu código decide según el código HTTP y el campo error, que no cambian.
• Campos nuevos. Las respuestas pueden incluir campos nuevos: ignora los que no conozcas.

Errores

Los códigos 2xx indican que la solicitud ha ido bien. En los demás casos, el cuerpo de la respuesta explica qué ha pasado:

{
  "error": "account_inactive",
  "message": "La cuenta de DIGO Email aún no está activa."
}

{
  "message": "Debes aceptar la declaración de consentimiento.",
  "errors": {
    "consent": ["Debes aceptar la declaración de consentimiento."]
  }
}

Límites

• Hasta 300 solicitudes por minuto por cada sitio conectado, contando todos los endpoints.
• Para POST /contacts, como máximo 60 suscripciones por minuto por sitio.
• Productos, artículos y pedidos pasados viajan en grupos de 100 por solicitud.
• Las respuestas indican el límite general (X-RateLimit-Limit) y cuántas solicitudes quedan en el minuto (X-RateLimit-Remaining). Al superar un límite recibes 429 con Retry-After.

Una solicitud que falló por un error de red, un 429 o un 5xx se puede repetir sin problema: pedidos, productos, artículos y carritos se actualizan por id y un contacto ya suscrito no se duplica. En cambio, los demás errores 4xx se repiten igual hasta que corrijas los datos.

Lista de endpoints

Cuenta y ajustes

Estos endpoints leen lo que has preparado en el panel: tu sitio los usa para que quien lo configura elija listas, etiquetas y campos.

GET /ping

Comprueba la clave y el estado de la cuenta. Llámalo cuando alguien pegue la clave en los ajustes de tu sitio y, de vez en cuando, para saber si la cuenta acepta suscripciones. La respuesta es la de Primeros pasos.

GET /lists

Las listas de la cuenta en orden alfabético, con el id que debes usar para suscribir contactos.

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

Con double_opt_in en true, quien se suscribe recibe un email para confirmar: queda suscrito, y recibe las campañas, solo después de confirmar.

GET /tags

Las etiquetas de la cuenta en orden alfabético. Para poner una etiqueta a un contacto basta su nombre: las que no existen se crean.

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

GET /fields

Los campos personalizados de los contactos, que creas en Contactos › Campos personalizados.

{
  "data": [
    { "key": "empresa", "label": "Empresa", "type": "text" },
    { "key": "nacimiento", "label": "Fecha de nacimiento", "type": "date" }
  ]
}

GET /forms

Los formularios de suscripción de las listas, con todo lo necesario para mostrarlos con el estilo de tu sitio. Es lo que usa el shortcode del plugin para WordPress.

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

{
  "data": [
    {
      "id": 5,
      "name": "Newsletter",
      "title": "Suscríbete a la newsletter",
      "action": "https://www.digo.email/f/k3Jd9QmZ2xTb7LpV4nWc8RyA1sGe6HuF",
      "locale": "es",
      "consent_text": "Acepto recibir comunicaciones por email de Rossi S.L. Puedo darme de baja en cualquier momento.",
      "labels": { "email": "Email", "optional": "opcional", "privacy": "Política de privacidad", "submit": "Suscríbete" },
      "privacy_url": "https://www.tusitio.es/privacidad",
      "double_opt_in": true,
      "fields": [
        { "name": "first_name", "label": "Nombre", "type": "text", "required": false },
        { "name": "fields[nacimiento]", "label": "Fecha de nacimiento", "type": "date", "required": false }
      ],
      "script": "https://www.digo.email/js/digo-form.js?v=3",
      "can_send": true
    }
  ]
}

El formulario no pasa por tu servidor: el navegador del visitante lo envía directamente a la dirección action, sin clave. El consentimiento, el doble opt-in y las protecciones contra abusos son los de los formularios de DIGO Email. Para crearlo:

• un <form method="post"> con action como destino;
• el campo email y los campos de fields, cada uno con su name, obligatorios cuando required es true;
• una casilla consent junto al texto consent_text y al enlace a privacy_url, más un campo oculto consent_text con el mismo texto;
• el script indicado en script. En los sitios de la cuenta (los dominios de envío verificados y los sitios conectados) envía el formulario sin salir de la página y muestra ahí la respuesta; en otros sitios, o sin el script, el visitante ve la respuesta en una página de DIGO Email.

No llames website a ningún campo: es la trampa para los programas automáticos y un formulario que lo rellena se ignora. Sin el enlace a la política de privacidad en los ajustes de la cuenta, la respuesta es 409 privacy_missing.

Contactos

POST /contacts

Suscribe a una persona que ha aceptado recibir tus emails: desde un formulario de tu sitio, en el checkout o al registrarse. Sin consentimiento no se guarda nada.

curl -X POST https://www.digo.email/api/v1/contacts \
  -H "Authorization: Bearer dge_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "lucia.garcia@example.com",
    "first_name": "Lucía",
    "last_name": "García",
    "list_ids": [5],
    "tags": ["Sitio web"],
    "fields": { "empresa": "García Diseño", "nacimiento": "1990-04-18" },
    "consent": true,
    "consent_text": "Quiero recibir la newsletter de Rossi S.L. con novedades y ofertas.",
    "source": "form",
    "form": "Pie de página",
    "language": "es",
    "page": "https://www.tusitio.es/contacto",
    "ip": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_6) AppleWebKit/605.1.15"
  }'

{ "status": "confirming" }

Quien ya está entre tus contactos

• Las listas y las etiquetas se añaden, nunca se quitan.
• El nombre y los apellidos se quedan como están; los campos personalizados solo se rellenan si están vacíos, y el idioma solo si no tiene uno.
• Quien ya está suscrito entra enseguida también en las listas con doble opt-in, sin otra confirmación.
• Quien se dio de baja tiene que confirmar desde su propio buzón, incluso para las listas sin doble opt-in: nadie puede volver a suscribirlo en su lugar. A las direcciones que rebotaron o marcaron los emails como spam no les enviamos nada.

Qué pasa después

• En cuanto el contacto queda suscrito, enseguida o cuando confirma, se ponen en marcha las automatizaciones Se suscribe a una lista y Recibe una etiqueta.
• Por encima del límite de contactos de tu cuenta la suscripción se guarda igualmente, pero las campañas y las automatizaciones se detienen hasta que compres más contactos o elimines algunos; al doble del límite, las nuevas suscripciones se rechazan con 409 contact_limit.
• En la ficha del contacto encuentras la suscripción con el texto del consentimiento, el sitio, la página y el formulario.

<?php
// La clave viene de una variable de entorno: no la escribas en el código.
$consentText = 'Quiero recibir la newsletter de Rossi S.L. con novedades y ofertas.';

if (empty($_POST['consentimiento'])) {
    exit('Para suscribirte marca la casilla del consentimiento.');
}

$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['nombre'] ?? ''),
        'list_ids' => [5],
        'consent' => true,
        'consent_text' => $consentText, // el mismo texto que se muestra junto a la casilla
        'source' => 'form',
        'language' => 'es',
        'page' => 'https://www.tusitio.es/contacto',
        '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' => 'Gracias, ya estás suscrito.',
    'confirming' => 'Casi listo: abre el email que te hemos enviado y confirma.',
    'limited' => 'Hoy no podemos enviarte más emails de confirmación: inténtalo de nuevo mañana.',
    'capped' => 'Hoy no podemos enviarte más emails de confirmación: inténtalo de nuevo mañana.',
];
if ($code === 200) {
    echo $messages[$body['status']] ?? $messages['subscribed'];
} else {
    error_log('DIGO Email: ' . ($body['message'] ?? 'HTTP ' . $code));
    echo 'No hemos podido completar la suscripción. Inténtalo de nuevo más tarde.';
}

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: 'lucia.garcia@example.com',
    list_ids: [5],
    consent: true,
    consent_text: 'Quiero recibir la newsletter de Rossi S.L. con novedades y ofertas.',
    source: 'checkout',
    language: 'es',
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.message);
console.log(data.status); // subscribed, confirming, limited o capped

Productos y artículos

Los productos y los artículos del blog que envías aquí aparecen en el editor de emails, en los bloques Productos y Artículos: quien escribe una campaña los elige de una lista, con título, imagen, precio y enlace ya preparados.

PUT /items

Crea o actualiza hasta 100 elementos por solicitud, reconocidos por type e id. Envíalos todos la primera vez y luego cada vez que cambien el título, el precio, la imagen o la disponibilidad.

curl -X PUT https://www.digo.email/api/v1/items \
  -H "Authorization: Bearer dge_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "type": "product",
        "id": "1042",
        "title": "Taza de cerámica esmaltada",
        "url": "https://www.tusitio.es/productos/taza-esmaltada",
        "image": "https://www.tusitio.es/media/taza-esmaltada.jpg",
        "excerpt": "Hecha a mano, 350 ml, apta para lavavajillas.",
        "price": 24.00,
        "sale_price": 19.90,
        "available": true
      },
      {
        "type": "post",
        "id": "87",
        "title": "Cómo elegir la taza adecuada",
        "url": "https://www.tusitio.es/blog/taza-adecuada",
        "image": "https://www.tusitio.es/media/blog-tazas.jpg",
        "excerpt": "Materiales, capacidad y cuidados: una guía en cinco minutos.",
        "published_at": "2026-10-12T08:00:00+02:00"
      }
    ]
  }'

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

saved cuenta los elementos guardados; skipped enumera los id omitidos por no tener nombre o una dirección válida.

DELETE /items/{type}/{id}

Quita de la lista un producto que ya no vendes o un artículo que ya no está publicado. Responde 204, sin contenido, aunque el elemento no estuviera. Los emails ya preparados que lo contienen no cambian.

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

Pedidos

Los pedidos sirven para medir cuánto vende cada campaña, poner en marcha las automatizaciones Hace una compra en la tienda y cerrar los carritos abandonados. Los compradores no se convierten en contactos: guardamos un pedido solo si quien compra ya está entre tus contactos o si llega desde el enlace de una campaña (consulta Ventas de las campañas). Los demás se descartan.

POST /orders

Registra un pedido o actualiza su estado. Envíalo cuando se crea y de nuevo con cada cambio (pago, reembolso, cancelación), siempre con el mismo id.

curl -X POST https://www.digo.email/api/v1/orders \
  -H "Authorization: Bearer dge_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "5531",
    "number": "#5531",
    "email": "lucia.garcia@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": "Taza de cerámica esmaltada", "quantity": 2, "total": 39.80 }
    ]
  }'

{ "attributed": true }

attributed es true cuando el pedido cuenta para una campaña. Un pedido que no afecta ni a un contacto ni a una campaña no se guarda y la respuesta es {"attributed": false, "stored": false}.

• Cuando un pedido pasa a paid por primera vez y quien compra es un contacto, se ponen en marcha las automatizaciones Hace una compra en la tienda.
• Un pedido pending o paid cierra los carritos abiertos de quien compra: los emails de carrito abandonado ya no salen.
• En los informes cuentan los pedidos pagados, menos los reembolsos. Los pendientes y los cancelados no cuentan.

POST /orders/history

Importa los pedidos pasados, hasta 100 por solicitud, dentro de orders y con los mismos campos que POST /orders. Valen las mismas reglas, pero estos pedidos describen lo que ya ha pasado: no ponen en marcha automatizaciones ni cierran carritos. Puedes enviarlos de nuevo: actualizan los mismos pedidos. Un email no válido simplemente no coincide con ningún contacto.

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

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

received cuenta los pedidos recibidos y stored los guardados porque son de tus contactos o llegaron desde una campaña.

Carritos

Con los carritos puedes recordar a los clientes lo que dejaron en tu tienda, con la automatización Abandona el carrito. En los emails, los marcadores {{carrello_link}}, {{carrello_totale}} y {{carrello_prodotti}} muestran el enlace para recuperar el carrito, el total y los productos.

PUT /carts

Guarda el carrito de un cliente cuyo email conoces, porque ha iniciado sesión o lo ha escrito en el checkout. Envíalo de nuevo con cada cambio, siempre con el mismo id. Solo guardamos los carritos de quien ya está entre tus contactos: nadie se convierte en contacto por llenar un carrito.

curl -X PUT https://www.digo.email/api/v1/carts \
  -H "Authorization: Bearer dge_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "c-8f2a1c",
    "email": "lucia.garcia@example.com",
    "total": 39.80,
    "currency": "EUR",
    "url": "https://www.tusitio.es/carrito?recuperar=8f2a1c",
    "items": [
      { "id": "1042", "name": "Taza de cerámica esmaltada", "quantity": 2, "total": 39.80, "image": "https://www.tusitio.es/media/taza-esmaltada.jpg" }
    ]
  }'

{ "saved": true }

Si el email no es de uno de tus contactos, la respuesta es {"saved": false} y se quita el carrito que se hubiera guardado antes con el mismo id.

DELETE /carts/{id}

Cierra un carrito que el cliente ha vaciado. Responde 204, sin contenido. Después de una compra no hace falta: el pedido ya cierra los carritos de quien compra.

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

Ventas de las campañas

Para decirte cuánto vende cada campaña, DIGO Email vincula los pedidos con los clics en los emails:

1. Cuando alguien hace clic en un enlace del email que lleva a tu sitio, añadimos a la dirección el parámetro digo_c, por ejemplo https://www.tusitio.es/productos/taza-esmaltada?digo_c=184467.9f1c2ab07d3e4f51. Vale para la dirección del sitio configurada en Integraciones y para sus subdominios.
2. Si el visitante ha aceptado las cookies de marketing, tu sitio guarda el valor en la cookie digo_c durante 7 días. Un clic más reciente sustituye al anterior.
3. Cuando el cliente compra, envías el valor de la cookie como click_id junto con el pedido.

El pedido cuenta para la campaña si llega en los 7 días siguientes al último clic en ese email. Si el cliente hizo clic en varios emails, vale el último.

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

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

La vinculación solo funciona con la medición de clics activada, en Ajustes › Empresa › Medir aperturas y clics: sin ella, los enlaces de los emails llevan directamente al sitio y no llevan digo_c.

Buenas prácticas

• Llama a la API desde tu servidor, nunca desde el navegador: la clave no debe salir de él.
• No hagas esperar a los clientes. En el checkout pon en cola las suscripciones, los pedidos y los carritos y envíalos justo después: si DIGO Email va lento o no responde, la compra no debe bloquearse.
• Reintenta con calma tras un error de red, un 429 o un 5xx, esperando un poco más cada vez. Las solicitudes con otros errores 4xx hay que corregirlas, no repetirlas.
• Pide el consentimiento con una casilla para marcar, no marcada de antemano, y envía en consent_text exactamente el texto que la persona leyó.
• Envía el idioma de quien se suscribe con language: los emails de confirmación, las campañas y las páginas de baja lo seguirán.
• Mantén el catálogo al día: envía los productos cuando cambien y quítalos cuando dejen de estar a la venta.
• Haz pruebas con una lista de prueba y direcciones tuyas. Las suscripciones de prueba son contactos reales: cuentan para el límite y, con doble opt-in, reciben emails reales. Al terminar, bórralos desde el panel.

Soporte

Si tienes dudas sobre la API, escribe a info@digo.email. Indica el nombre del sitio conectado, el endpoint y la respuesta recibida: nunca la clave.