Primeros pasos con el correo electrónico

Messages API de Vonage admite el correo electrónico como canal, lo que te permite enviar correos electrónicos transaccionales usando el mismo contrato de API que ya usas para otros canales de mensajería. Con una sola integración, puedes administrar todas tus comunicaciones salientes sin agregar un proveedor de correo electrónico separado a tu pila.

Esta guía le guiará a través de todo lo que necesita para enviar su primer correo electrónico utilizando la Messages API.

El canal Email se encuentra actualmente en fase Beta. Durante esta fase, la incorporación será gestionada por su Account Manager.

Requisitos previos

Antes de empezar, asegúrate de tener lo siguiente:

A Cuenta API de Vonage
Tu clave y secreto de API, disponibles en el panel de API de Vonage
Un dominio de envío verificado - véase Configuración de la autenticación de dominio debajo de
Acceso Beta al canal Email - contacte con su Account Manager

Incorporación por correo electrónico

Para embarcarte, sigue estos pasos:

Proporcione la siguiente información a su Account Manager:
- Tu clave API de Vonage
- El dominio o dominios personalizados desde los que enviará los correos electrónicos (por ejemplo, sudominio.com)
- Su región preferida para la verificación del dominio: EE.UU., UE o APAC

Sólo puede Verify un dominio en una región durante la Beta. Elija la región más cercana a sus usuarios o infraestructura.

Su Gestor de Account transmite la información al Gestor de Producto, que inicia el proceso de incorporación.
Vonage proporciona un conjunto de registros DNS que debes agregar a la configuración DNS de tu dominio. Ver Configuración de la autenticación de dominio para ver la lista completa de registros y lo que hace cada uno.
Una vez que haya actualizado sus registros DNS, confírmelo con su Account Manager. La verificación de DNS puede tardar hasta 72 horas en completarse.
Añada sus registros DNS con prontitud, la propagación puede tardar hasta 72 horas. Si tarda más de lo previsto, le recomendamos que genere nuevos registros DNS para su dominio.
Cuando se complete la verificación, Vonage notificará a tu administrador de cuenta y podrás comenzar a enviar correos electrónicos a través de Messages API.

Una vez que tu dominio esté verificado en una región, debes utilizar el punto final regional correspondiente para todas las solicitudes de correo electrónico. Las solicitudes enviadas a un endpoint regional diferente fallarán.

Región	Punto final
EU	https://api-eu.nexmo.com/v1/messages/
US	https://api-us.nexmo.com/v1/messages/
APAC	https://api-ap.nexmo.com/v1/messages/

Configuración de la autenticación de dominio

Antes de poder enviar correos electrónicos, debes autenticar tu dominio de envío. La autenticación de dominio mejora la capacidad de entrega de emails y permite que los proveedores de buzones verifiquen que Vonage está autorizado a enviar emails en tu nombre.

La autenticación se completa añadiendo registros DNS a la configuración DNS de su dominio. Estos registros permiten:

SPF (Sender Policy Framework): autoriza a la infraestructura de envío de Vonage a enviar en nombre de tu dominio.
DKIM (DomainKeys Identified Mail): firma criptográficamente los correos electrónicos salientes para que los servidores receptores puedan verificar que el contenido no ha sido manipulado.
DMARC (Domain-based Message Authentication, Reporting & Conformance): define la política de gestión de fallos de autenticación y proporciona informes.

Los principales proveedores de buzones de correo, como Google, Microsoft y Yahoo, confían en estos mecanismos para determinar si los correos electrónicos deben entregarse, rechazarse o marcarse como spam.

Registros DNS a configurar

Vonage proporciona los valores exactos de los registros DNS durante la incorporación. La siguiente tabla muestra la estructura y el tipo de cada registro que deberás agregar:

Tipo	Tipo de registro	Anfitrión / Llave	Valor	Descripción
AUTH	CNAME	`<dkim_key_1>._domainkey.<your_domain>`	`<dkim_value_1>.dkim.xxxx.com`	Registro DKIM
AUTH	CNAME	<`dkim_key_2>._domainkey.<your_domain>`	`<dkim_value_2>.dkim.xxxx.com`	Registro DKIM
AUTH	CNAME	`<dkim_key_3>._domainkey.<your_domain>`	`<dkim_value_3>.dkim.xxxx.com`	Registro DKIM
SEND	TXT	`_dmarc.<your_domain>`	`v=DMARC1; p=none;`	Política DMARC
SEND	TXT	`<your_domain>`	`v=spf1 include:.xxxx.com ~all`	Registro SPF

Envíe su primer correo electrónico

Una vez verificado su dominio, ya puede enviar mensajes de correo electrónico a través de la API de Messages.

Crear una aplicación de Vonage

Para usar Messages API, necesitas una aplicación de Vonage con la función Messages habilitada. La aplicación contiene tu configuración de webhook y credenciales de autenticación.

Ve a Crear una aplicación en el panel de Vonage.
Dale un nombre a tu aplicación.
Haga clic en Generar clave pública y privada. Su archivo de clave privada se descarga automáticamente - guárdelo de forma segura, ya que no se puede volver a descargar.
En CapacidadesActivar Mensajes.
Establezca la URL de entrada y la URL de estado en los puntos finales del webhook de su aplicación. Si aún no las tiene, puede utilizar URL de marcador de posición y actualizarlas más tarde.
Haga clic en Generar nueva aplicación.

Para más información, consulte Crear una aplicación de Vonage.

Establezca sus valores sustituibles

Los ejemplos de código de esta guía utilizan las siguientes variables. Sustituya cada una de ellas por sus valores reales antes de ejecutar los ejemplos.

Variable	Descripción
`VONAGE_API_KEY`	Tu clave de API de Vonage, que se encuentra en el panel de API.
`VONAGE_API_SECRET`	Tu secreto de API de Vonage.
`VONAGE_APPLICATION_ID`	El ID de la aplicación de Vonage.
`VONAGE_PRIVATE_KEY`	La ruta al archivo de la clave privada.
`FROM_EMAIL`	Su dirección de correo electrónico de remitente verificada (por ejemplo, support@yourdomain.com).
`TO_EMAIL`	La dirección de correo electrónico del destinatario.
`EMAIL_SUBJECT`	El asunto del correo electrónico.

Generar un JWT

La API Messages API utiliza JSON Web Tokens (JWTs) para la autenticación. Genere un JWT utilizando su ID de aplicación y su clave privada.

Enviar un mensaje de texto

Utilice la siguiente solicitud para enviar un correo electrónico de texto sin formato:

{
  "channel": "email",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "message_type": "text",
  "text": "Email body text",      
  "email": {
    "subject": "Email subject"  
  }
}

Si la solicitud se realiza correctamente, recibirá una respuesta con la información siguiente message_uuid:

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Enviar un correo electrónico HTML

Para enviar un correo electrónico con contenido HTML, configure message_type a "html" y escriba su código HTML en el campo del cuerpo:

{
  "channel": "email",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "message_type": "html",
  "html": {
    "body": "<p>Email body html</p>"
  },      
  "email": {
    "subject": "Email subject"  
  }
}

Comprobar el estado de la entrega

Luego de enviar un correo electrónico, Vonage envía actualizaciones de estado de entrega a la URL de estado configurada en tu aplicación de Vonage. Cada actualización es una solicitud POST que contiene el message_uuid y un campo de estado.

Los estados clave para el canal Email son:

Estado	Descripción
`submitted`	El correo electrónico ha sido aceptado y puesto en cola para su entrega.
`delivered`	El correo electrónico se ha entregado correctamente en el buzón del destinatario.
`read`	El destinatario ha abierto el correo electrónico.
`rejected`	El correo electrónico no ha podido ser entregado - compruebe el código de error para más detalles.

Precios por correo electrónico

Los precios de Email API se basan en suscripciones y están disponibles en seis niveles. Cada nivel incluye un número fijo de mensajes. Una vez que haya utilizado los correos electrónicos incluidos en su plan, se aplicarán cargos por exceso por correo electrónico. Para conocer los precios actuales, póngase en contacto con su gestor de Account.