Mail API

La API de correo convierte sus correos en mensajes: usted envía un correo a la dirección de su configuración, nosotros lo evaluamos con sus patrones y enviamos el resultado como SMS, RCS, WhatsApp o mensaje de voz. Dónde aparecen en el correo el destinatario, el texto y el remitente lo describe una sola vez en la configuración. Los destinatarios pueden ser números, contactos o grupos de su libreta de direcciones.

Dirección fija con patrones de correo

Cada configuración de la API de correo dispone de una dirección fija generada por el sistema y de tres patrones. Los patrones describen cómo son sus correos: dónde está el destinatario, dónde está el texto del mensaje y qué más contiene el correo. Así la API de correo se adapta a su aplicación. La configuración en sí se crea tal como se describe en la sección Configuración.

Estructura de la dirección

La dirección se compone de un token fijo y de un prefijo opcional delante:

TOKEN@gateway.seven.io
PREFIX.TOKEN@gateway.seven.io

El TOKEN lo generamos nosotros, es fijo y se muestra en su inicio de sesión en Desarrollador > Accesos API. El PREFIX lo elige usted para cada correo: todo lo que está antes del último punto de la parte local es el prefijo y se evalúa mediante el patrón del prefijo de la dirección.

Así, en la dirección 01761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io, a1b2c3d4e5f6g7h8 es el token y 01761234567890 es el prefijo.

Dirección corta sin token

Con la opción Dirección sin token activada en la configuración (posible en cuanto la comprobación DMARC está activa, véase Seguridad), el token puede omitirse: un correo a 01761234567890@gateway.seven.io se asigna entonces a la configuración únicamente por su dirección de remitente, y toda la parte local de la dirección es el prefijo. Aquí solo cuentan los remitentes acreditados (véase Seguridad). Si más de una configuración contiene el mismo remitente acreditado, no se usa ninguna; una dirección acreditada tiene prioridad sobre una entrada de dominio acreditada. La dirección con token sigue funcionando en cualquier caso.

Configuración en cinco pasos

El diálogo en Desarrollador > Accesos API le guía por los cinco pasos de una configuración. Se guarda en el último paso, y solo después de que haya llegado un correo de prueba de uno de los remitentes permitidos.

Variables

En los patrones dispone de las siguientes variables. La lista es definitiva, no existen otras variables.

Básicas

Ampliadas: {{delay}}, {{type}}, {{label}}, {{foreign_id}}, {{unicode}}, {{flash}}, {{performance_tracking}}, {{get_replies}}

El significado y los valores permitidos de estas variables se describen en la sección Formato clásico, en Parámetros, y se aplican aquí sin cambios. {{type}} sobrescribe para ese correo concreto el tipo establecido en la configuración. {{get_replies}} admite yes o no: con yes enviamos el mensaje desde un número que puede recibir respuestas, de modo que el destinatario pueda contestar directamente; un remitente indicado se sustituye por él.

WhatsApp: {{template}}, {{template_lang}}, {{header}}, {{body}}, {{buttons}}, {{media_url}}, {{media_type}}, {{caption}}

Estas variables rellenan los campos de un mensaje de WhatsApp; su significado se describe en la sección WhatsApp (WA).

La autenticación se basa en su dirección de remitente y en el token de la dirección; no existe ninguna clave.

Cada variable puede aparecer como máximo una vez en el conjunto de los tres patrones. {{text}} debe capturarse en alguno de los patrones y {{to}} debe capturarse o establecerse mediante Destinatario fijo.

Cómo evaluamos el correo

• El patrón del prefijo de la dirección debe cubrir el prefijo completo.
• En el asunto y en el cuerpo buscamos el patrón: el texto literal debe aparecer y las variables capturan el texto intermedio.
• Un patrón vacío significa que esa parte del correo se ignora.
• Un remitente capturado tiene prioridad sobre Remitente del mensaje, y un destinatario capturado sobre Destinatario fijo.
• Si un patrón no coincide con la parte correspondiente del correo, el mensaje no se envía.

Seguridad

La verificación del remitente se aplica sin cambios: solo aceptamos correos de una de las direcciones de remitente que haya indicado en la configuración correspondiente o de una dirección de un dominio allí indicado (*@dominio).

Comprobación DMARC

En cuanto todos los remitentes de una configuración están acreditados, la comprobación DMARC se activa automáticamente para ella, en el mismo momento en que llega la última acreditación, sin necesidad de ningún interruptor. En ese caso solo aceptamos un correo si el dominio remitente (el dominio de la dirección From) supera la comprobación DMARC en nuestra pasarela. Esto requiere un registro DMARC de su dominio junto con SPF o DKIM; un dominio sin registro DMARC nunca supera la comprobación. Los reenvíos no suponen un problema mientras la firma DKIM se mantenga intacta.

Una dirección de remitente se acredita enviando desde ella un correo de prueba a la dirección de prueba de la configuración que supere la comprobación DMARC. Una entrada de dominio (*@dominio) se acredita mediante un registro TXT seven-mail-api-verify=TOKEN en el dominio; además, el dominio (o un dominio superior) debe publicar un registro DMARC. Comprobamos ambos a diario y retiramos la acreditación si el registro TXT falta durante algunos días. Una configuración con la comprobación DMARC activa ya no admite remitentes sin acreditar; cree una segunda configuración para remitentes sin DMARC. La dirección sin token es una opción independiente que solo está disponible con la comprobación DMARC activa; déjela desactivada para combinar token y DMARC. Las entradas de dominio no son posibles para dominios de correo gratuito, y una dirección de remitente acreditada en una cuenta ya no puede indicarse en ninguna otra cuenta.

Un correo rechazado aparece con el código 904 en su Depurador. En ese caso, el correo de error se envía exclusivamente a la dirección de error indicada y nunca al remitente del correo, ya que este podría estar falsificado.

Ejemplos

Configuración predeterminada

Sin modificar los patrones, todo el cuerpo pasa a ser el texto del mensaje. El destinatario está establecido en la configuración y el correo se envía a la dirección sin prefijo.

Resultado: un SMS a 01761234567890 con el texto "Su paquete está en camino." El asunto se ignora.

Destinatario en la dirección

Si cada correo debe llegar a un número distinto, capture el destinatario con {{to}} en el prefijo de la dirección. Entonces no hace falta un destinatario fijo.

Resultado: un SMS a 01761234567890 con el texto "Su paquete está en camino."

Aviso en el asunto, destinatario fijo

Una herramienta de monitorización envía su aviso en el asunto a una dirección fija. El destinatario está establecido en la configuración.

Resultado: un SMS a 01761234567890 con el texto "Carga de CPU crítica en srv-07".

Patrón con anclas

Si el correo contiene algo más que el texto del mensaje, delimítelo con texto literal. Aquí dos pares de paréntesis encierran el texto, seguidos del momento de envío.

Resultado: un SMS a 01761234567890 con el texto "Su pedido está en camino.", programado para el 15 de enero de 2027 a las 08:00. La fecha del ejemplo representa cualquier momento futuro que su aplicación indique.

Manejo de errores

Si un patrón no coincide con la parte correspondiente del correo o si el destinatario queda vacío, el mensaje no se envía. Recibirá un correo de error indicando el motivo, siempre que haya activado la opción "Notificar en caso de errores". Con la comprobación DMARC activa, lo mismo se aplica a los correos cuyo dominio remitente no supere la comprobación DMARC; ese correo de error solo se envía a la dirección de error.

Configuración

En su inicio de sesión, en Desarrollador > Accesos API, gestiona sus configuraciones. Con el botón Crear nueva arriba a la derecha y la tarjeta Mail API crea una nueva; el diálogo le guía por los cinco pasos descritos arriba. Puede crear tantas configuraciones como desee, cada una con sus propios remitentes permitidos, su propia dirección fija y sus propios patrones. Solo se puede guardar después de un correo de prueba de uno de los remitentes permitidos; a partir de ahí la configuración se puede utilizar inmediatamente.

Los ajustes generales de la API de correo se encuentran en Desarrollador > Ajustes, en la sección Mail API.

Ajustes de Mail API

• Número máximo de caracteres: Establezca un número máximo de caracteres para evitar mensajes demasiado largos al incluir firmas. Ingrese 0 para desactivar esta función.
• Eliminar firma: Si está activado, la API intentará eliminar automáticamente el texto citado en el correo.
• Notificación en caso de error: Esta opción determina si desea recibir una notificación por correo en caso de errores. Por ejemplo, si el envío del mensaje falla, si un patrón no coincide con su correo o si faltan datos como el destinatario, le enviaremos directamente un correo con información sobre el error. Al crear una configuración, puede especificar opcionalmente una dirección de correo alternativa para recibir los mensajes de error.
• HTTP Push en caso de error: Si está activado, notificamos además los correos con error por HTTP a sus webhooks, con código y descripción del error.
• Insertar remitente en el SMS: Aquí puede configurar si desea enviar una parte de la dirección de correo al inicio de su mensaje. Puede elegir entre tres opciones:

Formato clásico

Las configuraciones creadas antes de la introducción de la dirección fija funcionan con el formato clásico: el destinatario está en la parte local de la dirección y los parámetros están en el asunto. En el dashboard aparecen marcadas como Legacy y siguen funcionando sin cambios y sin límite de tiempo. Las nuevas configuraciones utilizan patrones de correo.

Estructura del correo

Los correos dirigidos a una configuración Legacy tienen la estructura descrita a continuación. Las nuevas configuraciones utilizan en su lugar la dirección fija con patrones de correo.

Destinatario

Para enviar un mensaje a través de la API de correo, envíe un correo a destinatario@gateway.seven.io y reemplace destinatario con el número del destinatario o con el nombre de contacto de su libreta de direcciones.

Por ejemplo, si desea enviar un mensaje al número 01761234567890, el destinatario debe ser 01761234567890@gateway.seven.io.

Asunto

En el asunto, ingrese los parámetros necesarios para controlar el envío del mensaje. Estos deben estar separados por un espacio. Para establecer un parámetro, escriba el nombre del parámetro, seguido de un signo igual y el valor del parámetro.

Por ejemplo, con unParametro=unValor se establece el parámetro unParametro en unValor. Si el parámetro contiene espacios, debe encerrarlo entre comillas dobles " – por ejemplo, unParametro="Un valor con espacios".

Contenido

El texto del mensaje debe enviarse en el cuerpo del correo electrónico. El Gateway utiliza primero la parte text/plain del correo. Si el correo solo contiene una parte text/html sin alternativa de texto, se intentará analizarlo y extraer el texto del contenido HTML. Naturalmente, este método no siempre funciona como se desea.

Puede encerrar opcionalmente el texto del mensaje con ## para evitar que las líneas vacías o la firma del correo se incluyan en el mensaje. El texto se vería así: ##Este es el texto## - solo la parte entre ##...## se enviará en el mensaje.

Parámetros

Todos los parámetros se especifican en el asunto del correo como se mencionó anteriormente. Si no le es posible cambiar el asunto del correo, también puede especificar los parámetros en la dirección del destinatario de la siguiente manera:

• 01761234567890.from=ZahnPraxis@gateway.seven.io
• 01761234567890.from=ZahnPraxis.type=rcs@gateway.seven.io
• key=MAIL_API_KEY.from=ZahnPraxis.to=01761234567890@gateway.seven.io

Aquí hay un resumen de los posibles parámetros:

WhatsApp (WA)

La API de correo también envía mensajes de WhatsApp. En una configuración con patrones de correo, establezca el tipo en WhatsApp e indique su ID del servicio WhatsApp Frontend (Formato: WA-XXXXXXXX) como remitente del mensaje; en una configuración Legacy se establece type=WA y el parámetro from. Encontrará la ID en su panel de seven.io en WABA → Services. Los siguientes campos están disponibles en ambos casos: como variables en los patrones o como parámetros en el asunto.

Tipos de mensajes de WhatsApp

WhatsApp admite tres tipos de mensajes, que se determinan automáticamente según los parámetros:

si template != null:
    → Mensaje de plantilla
sino si media_url != null:
    → Mensaje multimedia
sino:
    → Mensaje de texto (cuerpo del correo)

Mensajes de plantilla

Los mensajes de plantilla son necesarios para mensajes fuera de la ventana de 24h y deben ser aprobados previamente por WhatsApp.

Mensajes multimedia

Los mensajes multimedia solo se pueden enviar dentro de la ventana de conversación de 24h.

Mensajes de texto

Para mensajes de texto simples dentro de la ventana de 24h, se utiliza el cuerpo del correo como mensaje.

Ejemplos de WhatsApp (formato clásico)

1. Mensaje de plantilla (fuera de la ventana de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=order_confirmation.template_lang=es_ES.body=Juan,12345@gateway.seven.io

2. Plantilla con imagen de encabezado

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=promo_image.header=https://example.com/promo.jpg.body=20%25-descuento@gateway.seven.io

3. Mensaje de texto (dentro de la ventana de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C@gateway.seven.io

4. Enviar imagen (dentro de la ventana de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=image.media_url=https://example.com/producto.jpg.caption=Su-producto@gateway.seven.io

5. Enviar documento

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=document.media_url=https://example.com/factura.pdf.caption=Su-factura@gateway.seven.io

Seguridad

El camino de transporte entre los distintos servidores SMTP o el cliente SMTP suele estar cifrado mediante TLS. Sin embargo, por varias razones, es recomendable cifrar el correo, por lo que la API de correo admite cifrado mediante PGP y S/MIME:

1. Confidencialidad: PGP y S/MIME cifran el contenido de los correos electrónicos, de modo que solo el destinatario previsto puede descifrarlos y leerlos. Esto garantiza la confidencialidad de la comunicación.

2. Autenticación: Ambos estándares permiten verificar la identidad del remitente. Las firmas digitales, creadas con la clave privada del remitente, permiten al destinatario asegurarse de que el correo electrónico realmente proviene de la fuente indicada y no ha sido manipulado.

3. Integridad: PGP y S/MIME ofrecen mecanismos para verificar la integridad de los correos electrónicos. Mediante firmas digitales, el destinatario puede asegurarse de que el contenido del correo no ha sido alterado desde su envío.

4. Defensa contra ataques Man-in-the-Middle: Mediante el cifrado y la autenticación, PGP y S/MIME ayudan a prevenir ataques Man-in-the-Middle, en los que un atacante intercepta, manipula y luego reenvía el tráfico de datos sin que las partes involucradas lo noten.

En general, PGP y S/MIME son útiles para garantizar la seguridad, confidencialidad e integridad de la comunicación por correo electrónico, especialmente en entornos donde se intercambian información sensible o confidencial.

Para un envío cifrado de los correos, descargue el certificado correspondiente e instálelo en su sistema. Dado que los certificados PGP y S/MIME solo pueden estar vinculados a una única dirección de correo electrónico, envíe sus correos a la dirección de correo electrónico indicada a continuación para el certificado.

El destinatario y otros datos se indican, como en el formato clásico, mediante los parámetros correspondientes en el asunto, por ejemplo to=017612345678.

Aquí puede descargar el certificado correspondiente:

DMARC, DKIM, SPF

DKIM, SPF y DMARC son mecanismos para mejorar la seguridad del correo electrónico. Ayudan a verificar la autenticidad de los correos electrónicos, combatir el spam y el phishing, así como mejorar la entregabilidad de los correos electrónicos.

Nuestra pasarela comprueba cada correo entrante frente a SPF, DKIM y DMARC. Por defecto, el resultado es solo informativo: lo que decide la aceptación sigue siendo la comparación con las direcciones de remitente indicadas. Solo cuando la comprobación DMARC de su configuración de Mail API está activa (todos los remitentes acreditados) se rechazan los correos cuyo dominio remitente no supera la comprobación DMARC (código 904, véase Seguridad más arriba). Puede ver los correos rechazados en su Depurador.

Ejemplos del formato clásico

Primer ejemplo

En el primer ejemplo, se envía un SMS al número 0163123456789 del remitente ZahnPraxis. La clave en este caso es email2sms_key.

El texto que se debe transmitir en el SMS es:

Hola Sr. Schubert, por la presente queremos recordarle su cita el 20 de enero en nuestra clínica. ¡Esperamos verle! Hasta entonces, su clínica dental

Segundo ejemplo

En este segundo ejemplo, se envía un SMS al contacto Bartscher del remitente Optiker. El número predeterminado 0163123456789, que está en el destinatario del correo, se sobrescribe mediante el parámetro to. La clave aquí es 123456789.

El texto que se debe transmitir en el SMS es:

Hola Sra. Bartscher, ¡sus gafas están listas! Por favor, recójalas pronto en nuestra tienda. ¡Esperamos verle! Hasta entonces, su óptica – la firma del correo al final no se enviará en el SMS, ya que el texto está delimitado por ##.

Tercer ejemplo

En este ejemplo, se envía un SMS al número 0163123456789. La configuración para el remitente se toma de las configuraciones predeterminadas de su cuenta en Configuración > SMS. La clave está integrada directamente en el destinatario del correo y se establece en abcd123456.

El texto que se debe transmitir en el SMS es:

Hola Sra. Bartscher, ¡sus gafas están listas! Por favor, recójalas pronto en nuestra tienda. ¡Esperamos verle! Hasta entonces, su óptica

La firma del correo al final no se enviará en el SMS, ya que el texto está delimitado por ##.

Legacy

Por razones de compatibilidad con versiones anteriores, la API de correo se mantiene en la antigua dirección de destinatario email2sms@sms77.de para correos en el formato de entonces. Los correos seguirán siendo procesados como de costumbre. Sin embargo, recomendamos cambiar a una configuración con dirección fija y patrones de correo para poder aprovechar todas las funcionalidades.