Saltar al contenido principal

Configuración de envíos de Email Marketing vía API

Team DataCrush

Esta guía explica cómo configurar, habilitar y utilizar envíos de Email Marketing vía API en DataCrush. Esta funcionalidad permite que un sistema externo, como un e-commerce, CRM, ERP o automatización propia, dispare correos individuales utilizando un envío de Email Marketing previamente configurado en DataCrush.

 

¿Qué es un envío de Email Marketing vía API?

Un envío de Email Marketing vía API es un envío diseñado para que un sistema externo determine a quién enviar y cuándo enviar, realizando una llamada a la API de DataCrush por cada destinatario.

A diferencia de un envío masivo tradicional:

  • No se seleccionan listas de destinatarios dentro de DataCrush.
  • El destinatario se informa en cada solicitud a la API.
  • El remitente, asunto y diseño del correo se configuran previamente en DataCrush.
  • Los contenidos dinámicos pueden personalizarse mediante variables.
  • Cada llamada a la API genera un envío individual.

Este tipo de envío es útil para comunicaciones automatizadas como confirmaciones, avisos, notificaciones, recordatorios o mensajes personalizados generados desde otro sistema.

 

Requisitos previos

Antes de crear un envío vía API, verificá que tu portal cumpla con los siguientes requisitos.

1. Módulo habilitado

Tu portal debe tener activo el módulo Email Marketing API.

Si el módulo no está habilitado, no verás la opción Crear envío para API dentro de Email Marketing.

2. Credenciales de API

Necesitás contar con las credenciales de acceso a la API:

Credencial Descripción
Portal ID Identificador numérico de tu portal
API Key Clave secreta de acceso a la API

Podés obtenerlas desde:

Configuraciones del portal > API

Importante: la API Key es confidencial. No debe compartirse públicamente ni exponerse en aplicaciones frontend, sitios web públicos o código visible por usuarios finales.

3. Dominio de envío autenticado

El dominio utilizado como remitente debe estar correctamente autenticado, especialmente en planes donde la autenticación del dominio sea obligatoria para habilitar envíos.

 

Cómo crear un envío de Email Marketing para API

Paso 1 — Crear el envío

  1. Ingresá a Email Marketing.
  2. Hacé clic en el botón Enviar email marketing.
  3. Abrí el desplegable del botón.
  4. Seleccioná Crear envío para API.
  5. Ingresá un nombre para identificar el envío.
  6. Confirmá la creación.

 

Paso 2 — Configurar el envío de Email Marketing

Desde la configuración del Email Marketing vas a poder definir los datos principales del envío.

Destinatarios

En los envíos vía API no es necesario seleccionar listas de destinatarios.

Los destinatarios se enviarán en cada solicitud realizada a la API.

Opcionalmente, podés utilizar listas de exclusión para evitar el envío a contactos que pertenezcan a determinadas listas.

Remitente

En esta sección configurás:

  • Remitente: cuenta desde la cual se enviará el correo.
  • Reply-to: cuenta que recibirá las respuestas.
  • Nuevo remitente: opción para crear un remitente si todavía no existe.

Contenido del email

En esta sección configurás:

  • Asunto
  • Vista previa o preheader
  • Diseño del correo
  • Variables dinámicas, si corresponde

Las variables pueden utilizarse en el asunto, la vista previa y el cuerpo del email.

 

Paso 3 — Diseñar el email

Desde la configuración del Email Marketing, ingresá al editor visual Drag & Drop para configurar el diseño del correo.

En el diseño podés incluir variables dinámicas, por ejemplo:

Hola {{first_name}}, tu pedido {{codigo_pedido}} fue confirmado.


También puedes agregar las variables desde el diseño de contenido dentro del Editor.



Al momento del envío, DataCrush reemplazará esas variables por los valores correspondientes.

 

Paso 4 — Habilitar el envío vía API

Una vez finalizada la configuración, hacé clic en Habilitar Email Marketing.

Luego confirmá la acción en el modal Habilitar envío vía API.

El modal muestra la siguiente información:

  • Endpoint de la API.
  • ID del envío, también llamado emailmarketing_id.
  • Enlace a la documentación técnica.

Después de confirmar, el envío pasa al estado Pendiente.

 

Paso 5 — Esperar el estado Corriendo

El Email Marketing puede demorar alrededor de un minuto en estar habilitado para su envío vía API.

Cuando el envío pasa al estado Corriendo, la API comienza a aceptar nuevas solicitudes.

El emailmarketing_id puede obtenerse desde:

  • El modal de habilitación.
  • La URL del reporte del envío.

Ejemplo:

/outbound/emails/report/?id=45678

En este caso, el emailmarketing_id es:

45678

 

Estados del envío

Estado Significado ¿Acepta envíos por API?
Borrador El envío fue creado, pero aún no fue habilitado No
Pendiente Fue habilitado y espera activación No
Corriendo Está activo y listo para recibir solicitudes API Sí
Pausado Fue detenido temporalmente No
Ejecutado / Finalizado Fue cerrado manualmente No
Cancelado Fue cancelado, por ejemplo por límites del plan No

En la lista de Email Marketing, los envíos creados para API se identifican con una insignia API.

 

Pausar, reanudar y finalizar un envío API

Pausar

Podés pausar un envío cuando está en estado Corriendo.

Para hacerlo:

  1. Ingresá a Email Marketing.
  2. Buscá el envío correspondiente.
  3. Abrí el menú Más.
  4. Seleccioná Pausar.

Efecto de la pausa:

  • El estado pasa a Pausado.
  • La API rechaza nuevas solicitudes.
  • Los correos que ya estaban pendientes de envío no se enviarán mientras el envío esté pausado.

No es posible editar el contenido de un envío mientras está corriendo o pausado. Para cambiar el diseño, cloná el envío y creá un nuevo envío para API.

Reanudar

Podés reanudar un envío cuando está en estado Pausado.

Para hacerlo:

  1. Ingresá a Email Marketing.
  2. Buscá el envío pausado.
  3. Abrí el menú Más.
  4. Seleccioná Reanudar.

El envío volverá al estado anterior, normalmente Corriendo, y la API volverá a aceptar solicitudes.

Finalizar

La opción Finalizar cierra definitivamente un envío vía API.

Para hacerlo:

  1. Ingresá a Email Marketing.
  2. Buscá el envío API.
  3. Abrí el menú Más.
  4. Seleccioná Finalizar.
  5. Confirmá la acción.

Efecto de finalizar:

  • El estado pasa a Ejecutado.
  • La API rechaza nuevas solicitudes de forma permanente.
  • No se puede volver a habilitar ese mismo envío vía API.

Mensaje de confirmación:

Una vez finalizado, este email marketing no puede habilitarse nuevamente vía API.

Si necesitás seguir enviando, deberás crear un nuevo envío para API.

 

Diferencia con envíos masivos tradicionales

Los envíos masivos tradicionales se ejecutan sobre una audiencia previamente seleccionada y pueden pasar automáticamente a Ejecutado cuando finaliza el envío.

En cambio, los envíos vía API permanecen en estado Corriendo hasta que sean finalizados manualmente. Esto permite que el sistema externo siga enviando solicitudes mientras el envío esté activo.

 

Variables dinámicas

Las variables son marcadores que se colocan en el asunto, vista previa o diseño del email. DataCrush las reemplaza por datos reales al preparar cada correo individual.

Sintaxis de variables

Tipo de variable Sintaxis Ejemplo
Campos dinámicos de contacto o API Doble llave {{first_name}}, {{codigo_pedido}}
Campos del sistema disponibles Doble llave {{current_year}}, {{contact_key}}, {{send_key}}

Reglas importantes

  • Los nombres de variables no distinguen mayúsculas y minúsculas.
  • {{Nombre}} y {{nombre}} se interpretan como la misma variable.
  • Si una variable no tiene valor, se reemplaza por texto vacío.
  • Las variables funcionan en asunto, vista previa y cuerpo del email.

 

Fuentes de valores para variables

Las variables pueden obtener valores desde distintas fuentes.

Fuente Origen ¿Actualiza la ficha del contacto?
Datos del contacto Base de contactos de DataCrush Ya están guardados
Variables enviadas por API Objeto variables de cada llamada No
first_name y last_name en la raíz del JSON Al usar create_contact: true Sí, al crear el contacto

Si una variable existe tanto en la ficha del contacto como en el objeto variables de la API, el valor enviado por API tiene prioridad para ese envío.

 

Variables del contacto

Son campos ya existentes en la ficha del contacto dentro de DataCrush.

Ejemplos:

{{email}}
{{first_name}}
{{last_name}}
{{mobile}}
{{phone}}

También pueden utilizarse campos personalizados definidos en:

Contactos > Configuración > Propiedades

Estos valores se completan automáticamente con los datos guardados en el contacto destinatario.

 

Variables personalizadas para API

Son variables que reciben valor únicamente cuando el sistema externo las envía dentro del objeto variables.

Ejemplos:

{{codigo_pedido}}
{{saldo}}
{{fecha_entrega}}
{{numero_reserva}}

Estas variables no se guardan en la ficha del contacto. Solo personalizan el contenido de ese envío específico.

 

Cómo insertar variables en el editor

Opción A — Campos de contacto

Dentro del editor de texto:

  1. Hacé clic en Personalización.
  2. Seleccioná el campo de contacto.
  3. El campo se insertará visualmente en el contenido.
  4. Al enviar, será reemplazado por el valor del contacto.

Esta opción se recomienda para datos que ya existen en la ficha del contacto, como nombre, apellido, email o campos personalizados.

Opción B — Variables personalizadas para API

Disponible únicamente en envíos creados con origen API.

Desde el editor:

  1. Abrí el menú Variables.
  2. Seleccioná Ingresar variable.
  3. Escribí el nombre de la variable.
  4. Confirmá la inserción.

Nombres permitidos:

Letras, números, guión, punto y guión bajo

Ejemplo:

codigo_pedido

Esta opción se recomienda para datos enviados por tu sistema externo en cada solicitud.

Opción C — Insertar variables manualmente en HTML

También podés escribir las variables directamente en el código HTML del bloque de texto.

Ejemplo:

<p>Hola {{first_name}}, tu pedido {{codigo_pedido}} fue confirmado.</p>

Esta opción es útil para:

  • Edición precisa del HTML.
  • Variables que no aparecen en el selector.
  • Variables dentro de atributos HTML, como href, alt o similares.

 

Variables en asunto y vista previa

También podés usar variables directamente en:

  • Asunto del email.
  • Vista previa o preheader.

Ejemplo de asunto:

Tu pedido {{codigo_pedido}} está en camino

Estas variables se reemplazan con los mismos valores utilizados en el cuerpo del email.

 

Uso de la API de envío

Para conocer el detalle técnico del endpoint, autenticación, campos disponibles, ejemplos de uso y posibles respuestas, consultá la documentación específica de la API:

https://help.datacrush.la/hc/es-419/articles/46215044068109-Env%C3%ADos-de-Email-Marketing-v%C3%ADa-API

 

Límites de uso

  • Se permite un máximo de 30 solicitudes por minuto por portal.
  • Se envía un destinatario por llamada.
  • Se permiten envíos duplicados al mismo contacto.
  • No hay deduplicación automática por destinatario.

 

Monitoreo y reportes

Para revisar el rendimiento del envío:

  1. Ingresá a Email Marketing.
  2. Abrí el reporte del envío correspondiente.
  3. Verificá las métricas disponibles.

Los envíos generados por API aparecen identificados con método de envío API.

Métricas disponibles:

  • Enviados.
  • Aperturas.
  • Clics.
  • Rebotes.
  • Desuscripciones.
  • Otras métricas del reporte de Email Marketing.

El reporte se actualiza a medida que se procesan los envíos.

 

Errores frecuentes

Error o situación Causa probable Solución
El email marketing no está en ejecución El envío no está en estado Corriendo Esperar la activación, reanudarlo o crear un nuevo envío
Falta la configuración de entrega El envío acaba de habilitarse y aún no está listo Esperar alrededor de un minuto
El email marketing no corresponde a un envío de API Se usó el ID de un envío masivo tradicional Usar el ID de un envío creado con Crear envío para API
El campo email no existe El contacto no existe en el portal Crear el contacto previamente o usar la opción correspondiente desde la API
Código 101 Se superó el límite de llamadas por minuto Espaciar las solicitudes
Código 100 Credenciales incorrectas Verificar Portal ID y API Key
Una variable aparece vacía No se envió valor y el contacto no tiene ese dato Enviar el valor en variables o completar el campo del contacto
La API responde OK pero no llega el mail El envío está pausado, finalizado o todavía no fue procesado Verificar estado Corriendo y revisar el reporte luego de unos minutos

 

Preguntas frecuentes

¿Puedo enviar si el envío no está en estado Corriendo?

No. El envío debe estar en estado Corriendo para que la API acepte solicitudes.

Después de habilitarlo, esperá alrededor de un minuto hasta que pase de Pendiente a Corriendo.

¿Puedo cambiar el diseño mientras el envío está corriendo?

No directamente. Pausar el envío tampoco habilita la edición del contenido.

Si necesitás modificar el diseño, cloná el envío y creá un nuevo envío para API.

¿Las variables enviadas por API actualizan el contacto?

No. Las variables del objeto variables solo personalizan ese envío específico.

Si necesitás actualizar datos permanentes del contacto, deberás hacerlo desde el panel de DataCrush o mediante la API de contactos.

¿Puedo usar el mismo envío API indefinidamente?

Sí. Podés usarlo mientras esté en estado Corriendo y no haya sido finalizado.

Cuando ya no lo necesites, se recomienda finalizarlo.

¿Puedo enviar varias veces al mismo contacto?

Sí. Cada llamada a la API genera un envío independiente, incluso si el destinatario ya recibió un correo anteriormente.

¿Necesito seleccionar listas?

No. En los envíos API, los destinatarios se informan en cada llamada mediante el campo email.

¿Dónde obtengo el emailmarketing_id?

Podés obtenerlo desde:

  • El modal que aparece al habilitar el envío vía API.
  • La URL del reporte del envío.

Ejemplo:

/outbound/emails/report/?id=45678

En este caso, el ID es:

45678

Resumen del flujo completo

  1. Crear un envío para API desde Email Marketing.
  2. Configurar remitente, asunto y diseño.
  3. Agregar variables dinámicas si corresponde.
  4. Habilitar el envío vía API.
  5. Esperar que pase de Pendiente a Corriendo.
  6. Copiar el emailmarketing_id.
  7. Desde tu sistema externo, realizar un envío por API por cada destinatario.
  8. Revisar el reporte del envío en DataCrush.
  9. Finalizar el envío cuando ya no se necesite.

 

Recomendaciones finales

  • No expongas el API Key en frontend.
  • Verificá que el envío esté en estado Corriendo antes de integrarlo.
  • Probá primero con un correo interno.
  • Controlá los límites de llamadas por minuto.
  • Revisá el reporte para validar envíos, aperturas y posibles errores.
  • Finalizá los envíos API que ya no estén en uso.

Relacionada con

Comentarios

0 comentarios

El artículo está cerrado para comentarios.