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 > Mail 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.

Configuración en cuatro pasos

El diálogo en Desarrollador > Mail API le guía por los cuatro pasos de una configuración.

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).

Ejemplos

Configuración predeterminada

Sin ninguna modificación, los patrones esperan el número de teléfono en el prefijo de la dirección y el texto del mensaje en el cuerpo.

Para:                          01761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io
Asunto:                        Aviso de paquete
Cuerpo:                        Su paquete está en camino.

Patrón del prefijo:            {{to}}
Patrón del asunto:             (vacío)
Patrón del cuerpo:             {{text}}

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

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.

Para:                          a1b2c3d4e5f6g7h8@gateway.seven.io
Asunto:                        Carga de CPU crítica en srv-07

Patrón del prefijo:            (vacío)
Patrón del asunto:             {{text}}
Patrón del cuerpo:             (vacío)
Destinatario fijo:             01761234567890

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.

Para:                          a1b2c3d4e5f6g7h8@gateway.seven.io
Cuerpo:                        ((Su pedido está en camino.)) delay=2027-01-15 08:00:00

Patrón del prefijo:            (vacío)
Patrón del cuerpo:             (({{text}})) delay={{delay}}
Destinatario fijo:             01761234567890

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".

Configuración

En su inicio de sesión en la sección Desarrollador bajo Mail API gestiona sus configuraciones. El ícono verde + en la parte inferior derecha crea una nueva; el diálogo le guía por los cuatro 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. Las configuraciones recién creadas se pueden utilizar inmediatamente después de guardar.

Al hacer clic en los engranajes azules, accederá a las opciones de configuración para la API de correo.

Configuración de la API de correo

• Longitud máxima: Establezca un número máximo de caracteres para evitar mensajes demasiado largos al incluir firmas. Ingrese 0 para desactivar esta función.
• Eliminar citas: Si está activado, la API intentará eliminar automáticamente el texto citado en el correo.
• Notificar 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.
• Incluir remitente del correo en el texto: 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.

La API de correo rechaza correos si no cumplen con los estándares de autenticación establecidos por su configuración de DKIM, SPF y DMARC. Esto puede ocurrir, por ejemplo, si un correo electrónico no tiene una firma DKIM válida, la dirección IP del remitente no está autorizada en los registros SPF o las políticas DMARC del propietario del dominio prevén el rechazo de correos electrónicos no autenticados.

Por favor, tenga esto en cuenta al implementar la API de correo. 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.