Inicio rápido: Envío de un correo electrónico mediante Azure Communication Services

  • Artículo

Nota:

Comparta su opinión y comentarios sobre Azure Communication Services con nosotros respondiendo a esta breve encuesta.

En este inicio rápido, obtendrá información sobre cómo enviar correo electrónico mediante los SDK de correo electrónico.

Introducción a Azure Communication Services mediante Try Email de Communication Services a fin de enviar mensajes de correo electrónico.

Requisitos previos

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Envío de un correo electrónico mediante Try Email

Probar Email ayuda a iniciar el envío de correos electrónicos a los destinatarios deseados mediante Azure Communication Services, así como a comprobar la configuración de la aplicación para enviar correos electrónicos. También ayuda a iniciar el desarrollo de notificaciones por correo electrónico con el fragmento de código de su lenguaje preferido.

Para enviar un mensaje a un destinatario y especificar el asunto y el cuerpo del mensaje,

  1. En la página de información general de un recurso de Azure Communication Services aprovisionado, haga clic en Probar correo electrónico en el panel de navegación izquierdo en Correo electrónico.

    Screenshot that shows the left navigation panel for Try Email.

  2. Seleccione uno de los dominios comprobados en la lista desplegable.

    Screenshot that shows the verfied domain from drop-down.

  3. Redacte el correo electrónico que se va a enviar

    • Escriba la dirección de correo electrónico del destinatario
    • Escriba el asunto
    • Escriba el cuerpo del mensaje del correo electrónico

    Screenshot that shows how to filter and select one of the verified email domains to connect.

  4. Haga clic en Enviar

    Screenshot that shows one of the verified email domains is now connected.

  5. Correo electrónico enviado correctamente.

    Screenshot that shows successful email send.

  6. Ahora también puede copiar el fragmento de código de ejemplo para enviar un correo electrónico que se usará en el proyecto de ejemplo para enviar notificaciones.

    • Seleccione el lenguaje que prefiera

    • Haga clic en Insertar mi conexión

    • Haga clic en Copiar

      Screenshot that shows code snippet to send email.

  7. El fragmento de código para enviar un correo electrónico ya está listo para usarse en el proyecto de notificación.

Introducción al uso de Azure Communication Services mediante la extensión de comunicación de la CLI de Azure para enviar mensajes de correo electrónico.

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Prerrequisitos

Comprobación de requisitos previos

  • En una ventana de terminal o comando, ejecute el comando az --version para comprobar que la CLI de Azure y la extensión de comunicación están instaladas.
  • Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.

Instalación

Adición de la extensión

Agregue la extensión Azure Communication Services para la CLI de Azure mediante el comando az extension.

az extension add --name communication

Inicio de sesión en la CLI de Azure

Deberá iniciar sesión en la CLI de Azure. Para iniciar sesión, ejecute el comando az login desde el terminal y proporcione sus credenciales.

Almacenamiento de la cadena de conexión en una variable de entorno

Puede configurar la variable de entorno AZURE_COMMUNICATION_CONNECTION_STRING para usar las operaciones de claves de la CLI de Azure sin tener que usar --connection_string para pasar la cadena de conexión. Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <connectionString> por la cadena de conexión real.

setx AZURE_COMMUNICATION_STRING "<yourConnectionString>"

Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Enviar un mensaje de correo electrónico

az communication email send
	--connection-string "yourConnectionString"
	--sender "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
	--to "<emailalias@emaildomain.com>"
	--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI."

Haga estas sustituciones en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <emailalias@emaildomain.com> por la dirección de correo electrónico a la que quiere enviar un mensaje.
  • Reemplace <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> por la dirección MailFrom del dominio comprobado.

El comando anterior también realiza un sondeo en el messageId y devuelve el estado de la entrega del correo electrónico. El estado puede ser uno de los siguientes:

Nombre del estado Descripción
NotStarted No estamos enviando este estado desde nuestro servicio en este momento.
En ejecución La operación de envío de correo electrónico está actualmente en curso y se está procesando.
Correcto La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico
Con error La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error.

Parámetros opcionales

Los siguientes parámetros opcionales están disponibles en la CLI de Azure.

  • --html se puede usar en lugar de --text para el cuerpo del correo electrónico HTML.

  • --importance establece el tipo de importancia para el correo electrónico. Los valores conocidos son: alto, normal y bajo. El valor predeterminado es normal.

  • --to establece la lista de destinatarios de correo electrónico.

  • --cc establece direcciones de correo electrónico de copia carbón.

  • --bcc establece direcciones de correo electrónico de copia oculta.

  • --reply-to establece la dirección de correo electrónico de respuesta.

  • --disable-tracking indica si el seguimiento de la involucración del usuario debe deshabilitarse para esta solicitud.

  • --attachments establece la lista de datos adjuntos de correo electrónico.

  • --attachment-types establece la lista de tipos de datos adjuntos de correo electrónico, en el mismo orden de los datos adjuntos.

También puede utilizar una lista de destinatarios con --cc y --bcc similar a --to. Es necesario que haya al menos un destinatario en --to o --cc o --bcc.

Para empezar a usar Azure Communication Services, utilice la biblioteca cliente de correo electrónico de C# de Communication Services para enviar mensajes por correo electrónico.

Sugerencia

Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.

Descripción del modelo de objetos de correo electrónico

Las clases e interfaces siguientes controlan algunas de las características principales de la biblioteca cliente de correo electrónico de Azure Communication Services para C#.

Nombre Descripción
EmailAddress Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar.
EmailAttachment Esta clase crea datos adjuntos de correo electrónico aceptando un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico y datos binarios para el contenido.
EmailClient La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico.
EmailClientOptions Esta clase se puede agregar a la creación de instancias de EmailClient para tener como destino una versión de API específica.
EmailContent Esta clase contiene el asunto y el cuerpo del mensaje de correo electrónico. Debe especificar al menos uno de los contenidos PlainText o Html
EmailCustomHeader Esta clase permite agregar un par nombre-valor para un encabezado personalizado. La importancia del correo electrónico también se puede especificar mediante estos encabezados con el nombre de encabezado "x-priority" o "x-msmail-priority".
EmailMessage Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta.
EmailRecipients Esta clase contiene listas de objetos EmailAddress para los destinatarios de mensajes de correo electrónico, incluyendo las listas opcionales para los destinatarios CC y CCO.
EmailSendOperation Esta clase representa la operación asincrónica de envío de correo electrónico y se devuelve desde la llamada API de envío de correo electrónico.
EmailSendResult Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda).

EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.

Estado Descripción
NotStarted No estamos enviando este estado desde nuestro servicio en este momento.
En ejecución La operación de envío de correo electrónico está actualmente en curso y se está procesando.
Correcto La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico
Con error La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error.

Requisitos previos

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Nota

También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute dotnet para comprobar que la biblioteca cliente de .NET esté instalada.
  • Para ver los subdominios asociados a su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal, busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.

Creación de una aplicación de C#

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre EmailQuickstart. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.

dotnet new console -o EmailQuickstart

Cambie el directorio a la carpeta de la aplicación recién creada y use el comando dotnet build para compilar la aplicación.

cd EmailQuickstart
dotnet build

Instalar el paquete

Mientras sigue en el directorio de aplicaciones, instale el paquete de la biblioteca cliente de correo electrónico de Azure Communication Services para .NET con el comando dotnet add package.

dotnet add package Azure.Communication.Email

Creación del cliente de correo electrónico con autenticación

Abra Program.cs y reemplace el código existente por lo siguiente para agregar directivas using a fin de incluir el espacio de nombres Azure.Communication.Email y un punto inicial para la ejecución de su programa.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

using Azure;
using Azure.Communication.Email;

namespace SendEmail
{
  internal class Program
  {
    static async Task Main(string[] args)
    {

    }
  }
}

Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:

Abra Program.cs en un editor de texto y reemplace el cuerpo del método Main por el código para inicializar EmailClient con la cadena de conexión. El siguiente código recupera la cadena de conexión para el recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING. Aprenda a administrar la cadena de conexión del recurso.

// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
EmailClient emailClient = new EmailClient(connectionString);

Envío de correo electrónico básico

Construcción del mensaje de correo electrónico

Para enviar un mensaje de correo electrónico, debe hacer lo siguiente:

  • Defina el asunto y el cuerpo del correo electrónico.
  • Defina la dirección del remitente. Cree el mensaje de correo electrónico con la información del remitente del que obtiene su dirección MailFrom del dominio comprobado.
  • Defina la dirección del destinatario.
  • Llame al método SendAsync. Agregue este código al final del método Main en Program.cs:

Reemplace por los detalles del dominio y modifique los detalles del contenido y destinatario según sea necesario.


//Replace with your domain and modify the content, recipient details as required

var subject = "Welcome to Azure Communication Service Email APIs.";
var htmlContent = "<html><body><h1>Quick send email test</h1><br/><h4>This email message is sent from Azure Communication Service Email.</h4><p>This mail was sent using .NET SDK!!</p></body></html>";
var sender = "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net";
var recipient = "emailalias@contoso.com";

Envío y obtención del estado de envío de correo electrónico

Para enviar un mensaje de correo electrónico, debe hacer lo siguiente:

  • Llame al método SendAsync que envía la solicitud de correo electrónico como una operación asincrónica. Llame con Azure.WaitUntil.Completed si su método debe esperar para devolver hasta que la operación de larga duración se haya completado en el servicio. Llame a con Azure.WaitUntil.Started si el método debe devolver después de iniciar la operación.
  • El método SendAsync devuelve EmailSendOperation que devuelve EmailSendStatus "Correcto" si el correo electrónico ha salido para la entrega y produce una excepción en caso contrario. Agregue este código al final del método Main en Program.cs:
try
{
    Console.WriteLine("Sending email...");
    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
        Azure.WaitUntil.Completed,
        sender,
        recipient,
        subject,
        htmlContent);
    EmailSendResult statusMonitor = emailSendOperation.Value;
    
    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");

    /// Get the OperationId so that it can be used for tracking the message for troubleshooting
    string operationId = emailSendOperation.Id;
    Console.WriteLine($"Email operation id = {operationId}");
}
catch (RequestFailedException ex)
{
    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
}

Obtención del estado de entrega de correos electrónicos

EmailSendOperation solo devuelve el estado de la operación de correo electrónico. Para obtener el estado real de entrega de correo electrónico, puede suscribirse al evento "EmailDeliveryReportReceived", que se genera cuando se completa la entrega de correo electrónico. El evento devuelve el siguiente estado de entrega:

  • Entregado.
  • Failed.
  • En cuarentena.

Consulte Control de eventos de Email para obtener más información.

Ahora puede suscribirse a los registros operativos de correo electrónico que proporcionan información relacionada con las métricas de entrega de los mensajes enviados desde el servicio de Correo electrónico.

  • Registros operativos de envío de correo electrónico: Proporciona información detallada relacionada con las solicitudes de correo de envío del servicio Correo electrónico.
  • Registros operativos de actualización de estado de correo electrónico: Proporciona actualizaciones del estado de entrega a nivel de mensajes y destinatarios, relacionadas con las solicitudes de correo de envío del servicio Correo electrónico.

Registros de acceso a Email Communication Service.

Ejecución del código

Ejecute la aplicación desde el directorio de la aplicación con el comando dotnet run.

dotnet run

Código de ejemplo

Puede descargar la aplicación de ejemplo de GitHub.

Para empezar a usar Azure Communication Services, utilice la biblioteca cliente de correo electrónico de JS de Communication Services para enviar mensajes por correo electrónico.

Sugerencia

Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.

Descripción del modelo de objetos de correo electrónico

Las clases e interfaces siguientes controlan algunas de las características principales de la biblioteca cliente de correo electrónico de Azure Communication Services para JavaScript.

Nombre Descripción
EmailAddress Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar.
EmailAttachment Esta clase crea datos adjuntos de correo electrónico aceptando un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico y datos binarios para el contenido.
EmailClient La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico.
EmailClientOptions Esta clase se puede agregar a la creación de instancias de EmailClient para tener como destino una versión de API específica.
EmailContent Esta clase contiene el asunto y el cuerpo del mensaje de correo electrónico. Debe especificar al menos uno de los contenidos PlainText o Html.
EmailCustomHeader Esta clase permite agregar un par nombre-valor para un encabezado personalizado. La importancia del correo electrónico también se puede especificar mediante estos encabezados con el nombre de encabezado "x-priority" o "x-msmail-priority".
EmailMessage Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta.
EmailRecipients Esta clase contiene listas de objetos EmailAddress para los destinatarios de mensajes de correo electrónico, incluyendo las listas opcionales para los destinatarios CC y CCO.
EmailSendResult Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda).
EmailSendStatus Esta clase representa el conjunto de estados de una operación de envío de correo electrónico.

EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.

Nombre del estado Descripción
isStarted Devuelve True si la operación de envío de correo electrónico está actualmente en curso y se está procesando.
IsCompleted Devuelve True si la operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico
resultado Propiedad que existe si la operación de envío de correo electrónico ha concluido.
error Propiedad que existe si la operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error.

Requisitos previos

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Nota

También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute node --version para comprobar que Node.js está instalado.
  • Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal, busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.

Configuración del entorno de la aplicación

Creación de una nueva aplicación Node.js

En primer lugar, abra la ventana de comandos o de terminal, cree un nuevo directorio para la aplicación y navegue hasta este.

mkdir email-quickstart && cd email-quickstart

Ejecute npm init -y para crear un archivo package.json con la configuración predeterminada.

npm init -y

Use un editor de texto para crear un archivo denominado send-email.js en el directorio raíz del proyecto. Cambie la propiedad "main" de package.json a "send-email.js". En la sección siguiente se muestra cómo agregar el código fuente de este inicio rápido al archivo recién creado.

Instalar el paquete

Use el comando npm install para instalar la biblioteca cliente de correo electrónico de Azure Communication Services para JavaScript.

npm install @azure/communication-email --save

La opción --save muestra la biblioteca como dependencia en el archivo package.json.

Creación del cliente de correo electrónico con autenticación

Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:

Importe la clase EmailClient desde la biblioteca cliente y cree una instancia con la cadena de conexión.

El código siguiente recupera la cadena de conexión del recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING mediante el paquete dotenv. Use el comando npm install para instalar el paquete dotenv. Aprenda a administrar la cadena de conexión del recurso.

npm install dotenv

Agregue el código siguiente a send-email.js:

const { EmailClient } = require("@azure/communication-email");
require("dotenv").config();

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
const emailClient = new EmailClient(connectionString);

Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.

Envío de correo electrónico básico

Enviar un mensaje de correo electrónico

Para enviar un mensaje de correo electrónico, llame a la función beginSend desde EmailClient. Este método devuelve un sondeo que comprueba el estado de la operación y recupera el resultado una vez finalizada.


async function main() {
  const POLLER_WAIT_TIME = 10
  try {
    const message = {
      senderAddress: "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
      content: {
        subject: "Welcome to Azure Communication Services Email",
        plainText: "This email message is sent from Azure Communication Services Email using the JavaScript SDK.",
      },
      recipients: {
        to: [
          {
            address: "<emailalias@emaildomain.com>",
            displayName: "Customer Name",
          },
        ],
      },
    };

    const poller = await emailClient.beginSend(message);

    if (!poller.getOperationState().isStarted) {
      throw "Poller was not started."
    }

    let timeElapsed = 0;
    while(!poller.isDone()) {
      poller.poll();
      console.log("Email send polling in progress");

      await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
      timeElapsed += 10;

      if(timeElapsed > 18 * POLLER_WAIT_TIME) {
        throw "Polling timed out.";
      }
    }

    if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
      console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
    }
    else {
      throw poller.getResult().error;
    }
  } catch (e) {
    console.log(e);
  }
}

main();

Haga estas sustituciones en el código:

  • Reemplace <emailalias@emaildomain.com> por la dirección de correo electrónico a la que quiere enviar un mensaje.
  • Reemplace <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> por la dirección MailFrom del dominio comprobado.

Ejecución del código

use el comando node para ejecutar el código que agregó al archivo send-email.js.

node ./send-email.js

Código de ejemplo

Puede descargar la aplicación de ejemplo de GitHub.

Introducción a Azure Communication Services mediante el SDK de correo electrónico de Communication Services para Java a fin de enviar mensajes de correo electrónico.

Sugerencia

Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.

Descripción del modelo de objetos de correo electrónico

Las clases e interfaces siguientes controlan algunas de las características principales del SDK de correo electrónico de Azure Communication Services para Python.

Nombre Descripción
EmailAddress Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar.
EmailAttachment Esta interfaz crea datos adjuntos de correo electrónico mediante la aceptación de un identificador único, una cadena tipo MIME de datos adjuntos de correo electrónico y una cadena de bytes de contenido.
EmailClient La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico.
EmailMessage Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta.
EmailSendResult Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda).
EmailSendStatus Esta clase representa el conjunto de estados de una operación de envío de correo electrónico.

EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.

Nombre del estado Descripción
NOT_STARTED No estamos enviando este estado desde nuestro servicio en este momento.
IN_PROGRESS La operación de envío de correo electrónico está actualmente en curso y se está procesando.
SUCCESSFULLY_COMPLETED La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico
FAILED La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error.

Requisitos previos

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Nota

También podemos enviar un correo electrónico desde nuestro propio dominio verificado Agregar dominios verificados personalizados a Email Communication Service.

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute mvn -v para comprobar que Maven está instalado.
  • Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.

Configuración del entorno de la aplicación

Para configurar un entorno a fin de enviar correos electrónicos, siga los pasos descritos en las secciones siguientes.

Creación de una aplicación Java

Abra la ventana de terminal o de comandos y navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecute el siguiente comando para generar el proyecto Java desde la plantilla maven-archetype-quickstart.

mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"

El objetivo generate crea un directorio con el mismo nombre que el valor artifactId. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de la prueba, y el archivo pom.xml es el modelo de objetos del proyecto (POM).

Instalar el paquete

Abra el archivo pom.xml en el editor de texto. Agregue el siguiente elemento de dependencia al grupo de dependencias.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

Instalación del marco de la aplicación

Abra /src/main/java/com/communication/quickstart/App.java en un editor de texto, agregue directivas de importación y quite la instrucción System.out.println("Hello world!");:

package com.communication.quickstart;

import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.PollResponse;
import com.azure.core.util.polling.SyncPoller;

public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

Creación del cliente de correo electrónico con autenticación

Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:

Para autenticar un cliente, cree una instancia EmailClient de con la cadena de conexión. Aprenda a administrar la cadena de conexión del recurso. También puede iniciar el cliente con cualquier cliente HTTP personalizado que implemente la interfaz com.azure.core.http.HttpClient.

Para crear una instancia de un cliente, agregue el siguiente código al método main:

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.

Envío de correo electrónico básico

Para enviar un mensaje de correo electrónico, llame a la función beginSend desde EmailClient. Este método devuelve un sondeo, que se puede usar para comprobar el estado de la operación y recuperar el resultado una vez finalizada. Tenga en cuenta que la solicitud inicial para enviar un correo electrónico no se enviará hasta que se llame al método poll o esperemos a que finalice el sondeador.

EmailMessage message = new EmailMessage()
    .setSenderAddress("<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>")
    .setToRecipients("<emailalias@emaildomain.com>")
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);
    Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);

    while (pollResponse == null
            || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
            || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
    {
        pollResponse = poller.poll();
        System.out.println("Email send poller status: " + pollResponse.getStatus());

        Thread.sleep(POLLER_WAIT_TIME.toMillis());
        timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);

        if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
        {
            throw new RuntimeException("Polling timed out.");
        }
    }

    if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
    {
        System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
    }
    else
    {
        throw new RuntimeException(poller.getFinalResult().getError().getMessage());
    }
}
catch (Exception exception)
{
    System.out.println(exception.getMessage());
}

Haga estas sustituciones en el código:

  • Reemplace <emailalias@emaildomain.com> por la dirección de correo electrónico a la que quiere enviar un mensaje.
  • Reemplace <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> por la dirección MailFrom del dominio comprobado.

Ejecución del código

  1. Vaya al directorio que contiene el archivo pom.xml y compile el proyecto mediante el comando mvn.

    mvn compile

  2. Compilar el paquete.

    mvn package

  3. Ejecute el siguiente comando mvn para ejecutar la aplicación.

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

Código de ejemplo

Puede descargar la aplicación de ejemplo de GitHub.

Introducción a Azure Communication Services mediante el SDK de correo electrónico de Communication Services para Python a fin de enviar mensajes de correo electrónico.

Sugerencia

Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.

Descripción del modelo de objetos de correo electrónico

La plantilla de mensaje JSON y objeto de respuesta siguientes muestran algunas de las características principales del SDK de correo electrónico de Azure Communication Services para Python.

message = {
    "content": {
        "subject": "str",  # Subject of the email message. Required.
        "html": "str",  # Optional. Html version of the email message.
        "plainText": "str"  # Optional. Plain text version of the email
            message.
    },
    "recipients": {
        "to": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "bcc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "cc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ]
    },
    "senderAddress": "str",  # Sender email address from a verified domain. Required.
    "attachments": [
        {
            "contentInBase64": "str",  # Base64 encoded contents of the attachment. Required.
            "contentType": "str",  # MIME type of the content being attached. Required.
            "name": "str"  # Name of the attachment. Required.
        }
    ],
    "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
    "headers": {
        "str": "str"  # Optional. Custom email headers to be passed.
    },
    "replyTo": [
        {
            "address": "str",  # Email address. Required.
            "displayName": "str"  # Optional. Email display name.
        }
    ]
}

response = {
    "id": "str",  # The unique id of the operation. Uses a UUID. Required.
    "status": "str",  # Status of operation. Required. Known values are:
        "NotStarted", "Running", "Succeeded", and "Failed".
    "error": {
        "additionalInfo": [
            {
                "info": {},  # Optional. The additional info.
                "type": "str"  # Optional. The additional info type.
            }
        ],
        "code": "str",  # Optional. The error code.
        "details": [
            ...
        ],
        "message": "str",  # Optional. The error message.
        "target": "str"  # Optional. The error target.
    }
}

Los valores response.status se explican con más detalle en la tabla siguiente.

Nombre del estado Descripción
InProgress La operación de envío de correo electrónico está actualmente en curso y se está procesando.
Correcto La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico
Con error La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error.

Requisitos previos

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

Nota

También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute python --version para comprobar que Python está instalado.
  • Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.

Configuración del entorno de la aplicación

Para configurar un entorno a fin de enviar correos electrónicos, siga los pasos descritos en las secciones siguientes.

Creación de una nueva aplicación de Python

  1. Abra el terminal o la ventana de comandos. A continuación, use el siguiente comando para crear un entorno virtual y activarlo. Este comando crea un nuevo directorio para la aplicación.

    python -m venv email-quickstart

  2. Vaya al directorio raíz del entorno virtual y actívelo con los siguientes comandos.

    cd email-quickstart
.\Scripts\activate

  3. Use un editor de texto para crear un archivo denominado send-email.py en el directorio raíz del proyecto y agregue la estructura del programa, incluido el control de excepciones básico.

    import os
from azure.communication.email import EmailClient

try:
    # Quickstart code goes here.
except Exception as ex:
    print('Exception:')
    print(ex)

En las secciones siguientes, agregará todo el código fuente de este inicio rápido al archivo send-email.py que ha creado.

Instalar el paquete

Mientras sigue en el directorio de la aplicación, instale el paquete del SDK de correo electrónico de Azure Communication Services para Python con el siguiente comando.

pip install azure-communication-email

Creación del cliente de correo electrónico con autenticación

Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:

Cree una instancia de EmailClient con la cadena de conexión. Aprenda a administrar la cadena de conexión del recurso.

# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)

Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.

Envío de correo electrónico básico

Enviar un mensaje de correo electrónico

Para enviar un mensaje de correo electrónico, debe hacer lo siguiente:

  • Construya el mensaje con los siguientes valores:
    • senderAddress: una dirección de correo electrónico de remitente válida, que se encuentra en el campo MailFrom en el panel de información general del dominio vinculado al recurso de Email de Communication Services.
    • recipients: objeto con una lista de destinatarios de correo electrónico y, opcionalmente, listas para los destinatarios CC y CCO de correo electrónico.
    • content: un objeto que contiene el asunto y, opcionalmente, el texto sin formato o el contenido HTML de un mensaje de correo electrónico.
  • Llame al método begin_send, que devuelve el resultado de la operación.
message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "<html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "<emailalias@emaildomain.com>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
}

poller = email_client.begin_send(message)
print("Result: " + poller.result())

Haga estas sustituciones en el código:

  • Reemplace <emailalias@emaildomain.com> por la dirección de correo electrónico a la que quiere enviar un mensaje.
  • Reemplace <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> por la dirección MailFrom del dominio comprobado.

Obtención del estado de la entrega del correo electrónico

Podemos sondear el estado de la entrega de correo electrónico estableciendo un bucle en el objeto de estado de la operación devuelto desde el método begin_send de EmailClient.

POLLER_WAIT_TIME = 10

try:
    email_client = EmailClient.from_connection_string(connection_string)

    poller = email_client.begin_send(message);

    time_elapsed = 0
    while not poller.done():
        print("Email send poller status: " + poller.status())

        poller.wait(POLLER_WAIT_TIME)
        time_elapsed += POLLER_WAIT_TIME

        if time_elapsed > 18 * POLLER_WAIT_TIME:
            raise RuntimeError("Polling timed out.")

    if poller.result()["status"] == "Succeeded":
        print(f"Successfully sent the email (operation id: {poller.result()['id']})")
    else:
        raise RuntimeError(str(poller.result()["error"]))

except Exception as ex:
    print(ex)

Ejecución del código

Ejecute la aplicación desde el directorio de la aplicación con el comando python.

python send-email.py

Código de ejemplo

Puede descargar la aplicación de ejemplo de GitHub.

Requisitos previos

Enviar correo electrónico

Para agregar un nuevo paso al flujo de trabajo mediante el conector de correo electrónico de Azure Communication Services, siga estos pasos:

  1. En el diseñador, abra el flujo de trabajo de la aplicación lógica.

    Consumo

    1. En el paso en el que quiera agregar la nueva acción, seleccione Nuevo paso. Como alternativa, para agregar la nueva acción entre pasos, mueva el puntero sobre la flecha entre esos pasos, seleccione el signo más (+) y seleccione Agregar una acción.

    2. En el cuadro de búsqueda Elegir una operación, seleccione Estándar. En el cuadro de búsqueda, introduzca el correo electrónico de Communication Services.

    3. En la lista de acciones, seleccione Enviar correo electrónico.

      Screenshot that shows the Azure Communication Services Email connector Send email action.

    Estándar

    1. En el paso en el que quiera agregar la nueva acción, seleccione el signo más (+). Como alternativa, para agregar la nueva acción entre pasos, mueva el puntero sobre la flecha entre esos pasos, seleccione el signo más (+) y seleccione Agregar una acción.

    2. En el cuadro de búsqueda Elegir una operación, seleccione Azure. En el cuadro de búsqueda, introduzca el correo electrónico de Communication Services.

    3. En la lista de acciones, seleccione Enviar correo electrónico.

  2. Proporcione un nombre para la conexión.

  3. Escriba la cadena de conexión para el recurso de Azure Communications Service. Para buscar esta cadena, siga estos pasos:

    1. En Azure Portal, abra el recurso de Azure Communication Service.

    2. En el menú de recursos, en Configuración, seleccione Claves y copie la cadena de conexión.

      Screenshot that shows the Azure Communication Services Connection String.

  4. Seleccione Crear cuando haya terminado.

  5. En el campo Desde, use la dirección de correo electrónico que configuró en los requisitos previos. Escriba los valores de los campos Para, Asunto y Cuerpo, por ejemplo:

    Screenshot that shows the Azure Communication Services Email connector Send email action input.

  6. Guarde el flujo de trabajo. En la barra de herramientas del diseñador, seleccione Save (Guardar).

Prueba del flujo de trabajo

En función de si tiene un flujo de trabajo de Consumo o Estándar, inicie manualmente el flujo de trabajo:

  • Consumo: en la barra de herramientas del diseñador, seleccione Ejecutar desencadenador>Ejecutar.
  • Estándar: en el menú del flujo de trabajo, seleccione Información general. En la barra de herramientas, seleccione Ejecutar desencadenador>Ejecutar.

El flujo de trabajo crea un usuario, emite un token de acceso para ese usuario y, a continuación, quita y elimina al usuario. Puede comprobar las salidas de estas acciones después de que el flujo de trabajo se ejecute correctamente.

Debería obtener un correo electrónico en la dirección especificada. También puede usar la acción Obtener estado del mensaje de correo electrónico para comprobar el estado de los correos electrónicos enviados a través de la acción Enviar correo electrónico. Para más acciones, revise la documentación de referencia del conector de correo electrónico de Azure Communication Services.

Limpieza de recursos de flujo de trabajo

Para limpiar el flujo de trabajo y el recurso de la aplicación lógica, así como los recursos relacionados, revise cómo limpiar los recursos de la aplicación lógica Consumo o cómo limpiar los recursos de la aplicación lógica Estándar.

Solución de problemas

Entrega de correo electrónico

Para solucionar incidencias relacionadas con la entrega de correo electrónico, puede obtener el estado de la entrega de correo electrónico para capturar los detalles de la entrega.

Importante

El resultado correcto devuelto por el sondeo del estado de la operación de envío solo valida el hecho de que el correo electrónico se haya enviado correctamente para su entrega. Para obtener información adicional sobre el estado de la entrega en el extremo del destinatario, deberá hacer referencia a cómo controlar los eventos de correo electrónico.

limitación de correo electrónico

Si ve que la aplicación se bloquea, podría deberse a que el envío de correo electrónico está limitado. Puede controlarlo mediante el registro o mediante la implementación de una directiva personalizada.

Nota

Esta configuración de espacio aislado sirve para ayudar a los desarrolladores a empezar a compilar la aplicación. Puede solicitar gradualmente aumentar el volumen de envío una vez que la aplicación esté lista para publicarse. Envíe una solicitud de soporte técnico para aumentar el límite de envío deseado si necesita enviar un volumen de mensajes que supere los límites de frecuencia.

Limpieza de recursos de Azure Communication Service

Para limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se eliminará cualquier otro recurso asociado. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes

En esta guía de inicio rápido, aprendió a enviar mensajes de correo electrónico mediante Azure Communication Services. También puede que desee consultar: