Compartilhar via

Início Rápido: Sondar manualmente status de email ao enviar email

  • Artigo

Neste início rápido, você aprenderá a sondar manualmente status de email ao enviar emails usando nossos SDKs do Email.

Começar a usar os Serviços de Comunicação do Azure usando a biblioteca de clientes de email .NET dos Serviços de Comunicação para enviar mensagens de email.

Dica

Inicie sua experiência de envio de email com os Serviços de Comunicação do Azure pulando diretamente para o código de exemplo Envio Básico de Email e Envio Avançado de Email no GitHub.

Noções básicas sobre o modelo de Objeto de E-mail

As classes e as interfaces a seguir lidam com alguns dos principais recursos da biblioteca de clientes de Email dos Serviços de Comunicação do Azure para C#.

Nome Descrição
EmailAddress Essa classe contém um endereço de email e uma opção para um nome de exibição.
EmailAttachment Essa classe cria um anexo de email aceitando uma ID exclusiva, uma cadeia de caracteres de tipo MIME de anexo de email, dados binários para conteúdo e uma ID de conteúdo opcional para defini-lo como um anexo embutido.
EmailClient Essa classe é necessária para toda a funcionalidade de email. Você cria uma instância com sua cadeia de conexão e a utiliza para enviar mensagens de email.
EmailClientOptions Essa classe pode ser adicionada à instanciação EmailClient para direcionar uma versão específica da API.
EmailContent Essa classe contém o assunto e o corpo da mensagem de email. Você precisa especificar pelo menos um conteúdo de texto não criptografado ou HTML
EmailCustomHeader Essa classe permite a adição de um par de nomes e valores a um cabeçalho personalizado. Email importância também pode ser especificada por meio desses cabeçalhos usando o nome de cabeçalho 'x-priority' ou 'x-msmail-priority'
EmailMessage Essa classe combina o remetente, o conteúdo e os destinatários. Cabeçalhos personalizados, anexos e endereços de email de resposta também podem ser adicionados.
EmailRecipients Essa classe contém listas de objetos EmailAddress para destinatários da mensagem de email, incluindo listas opcionais para destinatários CC e CCO.
EmailSendOperation Essa classe representa a operação de envio de e-mail assíncrono e é retornada da chamada à API de envio de e-mail.
EmailSendResult Essa classe contém os resultados da operação de envio de e-mail. Ele tem uma ID de operação, status da operação e objeto de erro (quando aplicável).

EmailSendResult retorna o seguinte status na operação de e-mail executada.

Status Descrição
NotStarted Não estamos enviando esse status de nosso serviço no momento.
Executando A operação de envio de e-mail está em andamento e está sendo processada.
Com sucesso A operação de envio de e-mail foi concluída sem erro e o e-mail está fora para entrega. Qualquer status detalhado sobre a entrega de e-mail além desse estágio pode ser obtido por meio do Azure Monitor ou de Grade de Eventos do Azure. Saiba como assinar o e-mail de eventos
Com falha A operação de envio de e-mail não foi bem-sucedida e encontrou um erro. Este e-mail não foi enviado. O resultado contém um objeto de erro com mais detalhes sobre o motivo da falha.

Pré-requisitos

A realização deste início rápido gera um pequeno custo de alguns centavos de dólar ou menos em sua conta do Azure.

Observação

Também podemos enviar um e-mail de nosso próprio domínio verificado. Como adicionar domínios verificados ao Serviço de Comunicação por E-mail.

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute o comando dotnet para verificar se a biblioteca de clientes do .NET está instalada.
  • Para exibir os subdomínios associados ao seu recurso dos Serviços de Comunicação por Email, entre no portal do Azure, localize o recurso em questão e abra a guia Provisionar domínios no painel de navegação esquerdo.

Criar um aplicativo em C#

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome EmailQuickstart. Esse comando cria um projeto simples C# "Olá, Mundo" com um arquivo de origem único: Program.cs.

dotnet new console -o EmailQuickstart

Altere o seu diretório para a pasta de aplicativo recém-criada e use o comando dotnet build para compilar o seu aplicativo.

cd EmailQuickstart
dotnet build

Instalar o pacote

Ainda no diretório do aplicativo, instale o pacote da biblioteca de clientes de Email dos Serviços de Comunicação do Azure para .NET usando o comando dotnet add package.

dotnet add package Azure.Communication.Email

Criando o cliente de e-mail com autenticação

Abra Program.cs e substitua o código existente pelo seguinte para adicionar diretivas using para incluir o namespace Azure.Communication.Email e um ponto de partida para execução do 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)
    {

    }
  }
}

Existem algumas opções diferentes disponíveis para autenticar um cliente de email:

Abra Program.cs em um editor de texto e substitua o corpo do método Main pelo código para inicializar um EmailClient com a cadeia de conexão. O código abaixo recupera a cadeia de conexão do recurso em uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu 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);

Enviar e-mail assíncrono e sondagem para o status de envio de e-mail

Quando você chama SendAsync com Azure.WaitUntil.Started, seu método retorna após iniciar a operação. O método retorna o objeto EmailSendOperation. Você pode chamar o método UpdateStatusAsync para atualizar o status da operação de e-mail.

O objeto EmailSendOperation retornado contém um objeto EmailSendStatus que contém:

  • Status atual da operação de Envio de E-mail.
  • Um objeto de erro com detalhes de falha se o status atual estiver em um estado de falha.

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

Execute o aplicativo do seu diretório de aplicativo com o comando dotnet run.

dotnet run

Código de exemplo

É possível baixar o aplicativo de exemplo do GitHub

Solução de problemas

Entrega de Emails

Para solucionar problemas relacionados à entrega de emails, você pode obter o status da entrega do email para capturar os detalhes da entrega.

Importante

O resultado de êxito retornado pela sondagem para o status da operação de envio só valida o fato de que o email foi enviado com êxito para entrega. Para obter informações adicionais sobre o status da entrega no destinatário final, você precisará consultar como lidar com eventos de email.

Limitação de Emails

Se você vir que seu aplicativo está travando, pode ser devido à limitação de envio de emails. Você pode lidar com isso através do registro em log ou implementando uma política personalizada.

Observação

Essa configuração de área restrita é para ajudar os desenvolvedores a começar a criar o aplicativo. Você pode solicitar gradualmente para aumentar o volume de envio quando o aplicativo estiver pronto para entrar em operação. Envie uma solicitação de suporte para aumentar o limite de envio desejado se você precisar enviar um volume de mensagens que exceda os limites de taxa.

Limpar recursos do Serviço de Comunicação do Azure

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele. Saiba mais sobre como limpar recursos.

Próximas etapas

Neste início rápido, você aprendeu a pesquisar manualmente o status ao enviar emails usando os Serviços de Comunicação do Azure.

Você também pode querer: