Inicio rápido: Sondeo manual del estado del correo electrónico al enviar correo electrónico

Artículo
12/04/2024

En este inicio rápido, obtendrá información sobre cómo sondear manualmente el estado del correo electrónico al enviar correo electrónico mediante nuestros SDK de Email.

Para empezar a usar Azure Communication Services, utilice la biblioteca cliente de correo electrónico de Communication Services .NET 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 al aceptar un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico, datos binarios para el contenido y un identificador de contenido opcional para definirlo como datos adjuntos insertados.
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

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
La versión más reciente de la biblioteca cliente de .NET Core para su sistema operativo.
Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Comenzar con la creación de un recurso de comunicación por correo electrónico
Un recurso activo de Communication Services conectado con el dominio de correo electrónico y una cadena de conexión. Comenzar conectando el recurso de correo electrónico con un recurso de comunicación

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

Para autenticarse mediante Azure Active Directory, instale el paquete de la biblioteca Azure.Identity para .NET mediante el comando dotnet add package.

dotnet add package Azure.Identity

Abra Program.cs en un editor de texto y reemplace el cuerpo del método Main por el código para inicializar EmailClient mediante DefaultAzureCredential. El SDK de Azure Identity lee valores de tres variables del entorno de ejecución para autenticar la entidad de servicio. Aprenda a crear una aplicación registrada en Azure Active Directory y a establecer las variables de entorno.

// This code demonstrates how to authenticate to your Communication Service resource using
// DefaultAzureCredential and the environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID,
// and AZURE_CLIENT_SECRET.
string resourceEndpoint = "<ACS_RESOURCE_ENDPOINT>";
EmailClient emailClient = new EmailClient(new Uri(resourceEndpoint), new DefaultAzureCredential());

Los clientes de correo electrónico también se pueden autenticar mediante AzureKeyCredential. Tanto key como endpoint se pueden basar en el panel "Claves" en "Configuración" en el recurso de Communication Services.

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = new Uri("<your-endpoint-uri>");

var emailClient = new EmailClient(endpoint, key);

Envío de correo electrónico asincrónico y sondeo para el estado de envío de correo electrónico

Al llamar a SendAsync con Azure.WaitUntil.Started, el método vuelve después de iniciar la operación. El método devuelve un objeto EmailSendOperation. Puede llamar al método UpdateStatusAsync para actualizar el estado de la operación de correo electrónico.

El objeto EmailSendOperation devuelto contiene un objeto EmailSendStatus que contiene:

Estado actual de la operación de envío de correo electrónico.
Un objeto de error con detalles de error si el estado actual está en un estado de error.


//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";

/// Send the email message with WaitUntil.Started
EmailSendOperation emailSendOperation = await emailClient.SendAsync(
    Azure.WaitUntil.Started,
    sender,
    recipient,
    subject,
    htmlContent);

/// Call UpdateStatus on the email send operation to poll for the status
/// manually.
try
{
    while (true)
    {
        await emailSendOperation.UpdateStatusAsync();
        if (emailSendOperation.HasCompleted)
        {
            break;
        }
        await Task.Delay(100);
    }

    if (emailSendOperation.HasValue)
    {
        Console.WriteLine($"Email queued for delivery. Status = {emailSendOperation.Value.Status}");
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Email send failed with Code = {ex.ErrorCode} and Message = {ex.Message}");
}

/// 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}");

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.

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

Si quiere 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 elimina cualquier otro recurso que esté asociado a él. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes

En este inicio rápido, ha aprendido a sondear manualmente el estado al enviar correo electrónico mediante Azure Communication Services.

Puede que también le interese:

Aprenda cómo enviar un correo electrónico a varios destinatarios
Más información sobre el envío de correo electrónico con datos adjuntos
Familiarizarse con la biblioteca cliente de correo electrónico

Compartir vía