Guia de início rápido: pesquisar manualmente o status do e-mail ao enviar e-mails

Neste início rápido, você aprenderá sobre como pesquisar manualmente o status do e-mail ao enviar e-mails usando nossos SDKs de e-mail.

Comece a usar os Serviços de Comunicação do Azure usando a biblioteca de cliente de Email .NET dos Serviços de Comunicação para enviar mensagens de email.

Gorjeta

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 de Email Básico e Envio de Email Avançado no GitHub.

Noções básicas sobre o modelo de objeto de e-mail

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

Nome	Descrição
EmailAddress	Esta classe contém um endereço de e-mail e uma opção para um nome de exibição.
EmailAttachment	Essa classe cria um anexo de email aceitando uma ID exclusiva, cadeia de caracteres do tipo MIME do anexo de email, dados binários para conteúdo e uma ID de conteúdo opcional para defini-lo como um anexo embutido.
EmailClient	Esta classe é necessária para todas as funcionalidades de e-mail. Você o instancia com sua cadeia de conexão e o usa para enviar mensagens de email.
EmailClientOptions	Essa classe pode ser adicionada à instanciação EmailClient para direcionar uma versão específica da API.
EmailContent	Esta classe contém o assunto e o corpo da mensagem de email. Você precisa especificar pelo menos um dos conteúdos PlainText ou Html
EmailCustomHeader	Essa classe permite a adição de um par de nome e valor para um cabeçalho personalizado. A importância do e-mail também pode ser especificada através desses cabeçalhos usando o nome do cabeçalho 'x-priority' ou 'x-msmail-priority'
Mensagem de e-mail	Essa classe combina o remetente, o conteúdo e os destinatários. Opcionalmente, também podem ser adicionados cabeçalhos, anexos e endereços de e-mail de resposta personalizados.
Destinatários de e-mail	Esta classe contém listas de objetos EmailAddress para destinatários da mensagem de email, incluindo listas opcionais para destinatários CC ou BCC.
EmailSendOperation	Essa classe representa a operação assíncrona de envio de email e é retornada da chamada api de envio de email.
EmailSendResult	Esta classe contém os resultados da operação de envio de e-mail. Ele tem um ID de operação, status da operação e objeto de erro (quando aplicável).

EmailSendResult retorna o seguinte status na operação de email executada.

Status	Description
NotStarted	Não estamos enviando esse status do nosso serviço no momento.
Em Execução	A operação de envio de e-mail está atualmente em andamento e sendo processada.
Com êxito	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 email além desse estágio pode ser obtido por meio do Azure Monitor ou da Grade de Eventos do Azure. Saiba como subscrever eventos por e-mail
Com falhas	A operação de envio de e-mail não foi bem-sucedida e encontrou um erro. O e-mail não foi enviado. O resultado contém um objeto de erro com mais detalhes sobre o motivo da falha.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• A biblioteca de cliente .NET Core versão mais recente para o seu sistema operacional.
• Um recurso dos Serviços de Comunicação de Email do Azure criado e pronto com um domínio provisionado Introdução à criação de recurso de comunicação por email
• Um recurso ativo dos Serviços de Comunicação conectado ao Domínio de Email e a uma Cadeia de Conexão. Comece conectando um recurso de email com um recurso de comunicação

A conclusão deste início rápido implica um pequeno custo de alguns cêntimos de USD ou menos na sua conta do Azure.

Nota

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

Verificação de pré-requisitos

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

Criar um novo aplicativo C#

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

dotnet new console -o EmailQuickstart

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

cd EmailQuickstart
dotnet build

Instalar o pacote

Enquanto ainda estiver no diretório do aplicativo, instale a biblioteca de cliente de Email dos Serviços de Comunicação do Azure para o pacote .NET usando o dotnet add package comando.

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 using diretivas para incluir o Azure.Communication.Email namespace e um ponto de partida para execução do seu 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 e-mail:

Cadeia de Ligação

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

Azure Active Directory

Para autenticar usando o Azure Ative Directory, instale o pacote de Azure.Identity biblioteca para .NET usando o dotnet add package comando.

dotnet add package Azure.Identity

Abra Program.cs em um editor de texto e substitua o Main corpo do método por código para inicializar um EmailClient usando DefaultAzureCredential. O SDK do Azure Identity lê valores de três variáveis de ambiente em tempo de execução para autenticar o aplicativo. Saiba como criar um Aplicativo Registrado do Ative Directory do Azure e definir as variáveis de ambiente.

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

AzureKeyCredential

Os clientes de email também podem ser autenticados usando uma AzureKeyCredential. Tanto o key e o endpoint podem ser encontrados no painel "Chaves" em "Configurações" no seu Recurso de Serviços de Comunicação.

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

var emailClient = new EmailClient(endpoint, key);

Envio assíncrono de e-mail 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 email.

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

• Status atual da operação Enviar 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 a partir do diretório do aplicativo com o dotnet run comando.

dotnet run

Código de exemplo

Você pode baixar o aplicativo de exemplo do GitHub

Resolução de Problemas

Entrega de e-mail

Para solucionar problemas relacionados à entrega de e-mails, você pode obter o status da entrega de e-mails para capturar detalhes de entrega.

Importante

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

Limitação de e-mail

Se você vir que seu aplicativo está travado, pode ser devido ao envio de e-mail estar limitado. Você pode lidar com isso por meio de registro em log ou implementando uma política personalizada.

Nota

Esta configuração de sandbox é para ajudar os desenvolvedores a começar a criar o aplicativo. Você pode solicitar gradualmente para aumentar o volume de envio assim que o aplicativo estiver pronto para entrar em operação. Envie uma solicitação de suporte para aumentar o limite de envio desejado se 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, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele. Saiba mais sobre a limpeza de recursos.

Próximos passos

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

Você também pode querer:

• Saiba como enviar e-mails para vários destinatários
• Saiba mais sobre como enviar e-mails com anexos
• Familiarize-se com a biblioteca de cliente de e-mail