Compartilhar via

Início Rápido: como enviar um email usando os Serviços de Comunicação do Azure

  • Artigo

Observação

Compartilhe seus pensamentos e comentários sobre os Serviços de Comunicação do Azure conosco fazendo esta breve pesquisa.

Este guia de início rápido descreve como enviar emails usando nossos SDKs de Email.

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

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.

Enviar um email usando o Try Email

O Try Email ajuda você a começar a enviar emails para os destinatários desejados usando os Serviços de Comunicação do Azure e verificar a configuração para que seu aplicativo envie emails. Além disso, ajuda a iniciar o desenvolvimento de notificações por email com o snippet de código no idioma de sua preferência.

Para enviar uma mensagem a um destinatário e especificar o assunto e o corpo da mensagem,

  1. Na página de visão geral de um recurso provisionado do Serviço de Comunicação do Azure, clique em Experimentar Email no painel de navegação esquerdo em Email.

    Captura de tela que mostra o painel de navegação esquerdo do Try Email.

  2. Selecione um dos domínios verificados na lista suspensa.

    Captura de tela que mostra o domínio verificado no menu suspenso.

  3. Redigir o email a ser enviado

    • Insira o endereço de email do destinatário
    • Insira o Assunto
    • Escreva o corpo do email

    Captura de tela que mostra como filtrar e selecionar um dos domínios de email verificados para se conectar.

  4. Clique em Enviar

    Captura de tela mostrando que um dos domínios de email verificados agora está conectado.

  5. Email enviado com sucesso.

    Captura de tela que mostra o envio bem-sucedido do email.

  6. Agora você também pode copiar o exemplo de Snippet de Código para enviar um email e usá-lo em seu projeto de amostra para enviar notificações.

    • Selecione um Idioma de sua preferência

    • Clique em Inserir minha Conexão

    • Clique em Copiar

      Captura de tela que mostra o snippet de código para enviar emails.

  7. O Snippet de Código de Email agora está pronto para ser usado em seu projeto de notificações.

Comece a usar os Serviços de Comunicação do Azure por meio da extensão de comunicação da CLI do Azure para enviar mensagens de email.

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.

Pré-requisitos

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute o comando az --version para verificar se a CLI do Azure e a extensão de comunicação estão instaladas.
  • Para ver os domínios verificados com o recurso dos Serviços de Comunicação por Email, entre no portal do Azure. Localize o recurso dos Serviços de Comunicação por Email e abra a guia Provisionar domínios no painel de navegação à esquerda.

Configurando

Adicionar a extensão

Adicione a extensão dos Serviços de Comunicação do Azure para a CLI do Azure usando o comando az extension.

az extension add --name communication

Entrar na CLI do Azure

Será necessário entrar na CLI do Azure. Para se conectar, execute o comando az login no terminal e forneça suas credenciais.

Armazenar a sua cadeia de conexão em uma variável de ambiente

Você pode configurar a variável de ambiente AZURE_COMMUNICATION_CONNECTION_STRING para usar operações de chaves da CLI do Azure sem precisar usar --connection_string para passar a cadeia de conexão. Para configurar uma variável de ambiente, abra uma janela do console e selecione o sistema operacional nas guias abaixo. Substitua <connectionString> pela cadeia de conexão real.

Observação

Não armazene sua cadeia de conexão como uma variável de ambiente não criptografada para ambientes de produção. Isso serve apenas para fins de teste. Para ambientes de produção, gere novas cadeias de conexão. Incentivamos você a criptografar cadeias de conexão e alterá-las regularmente.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

Enviar uma mensagem de email

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."

Faça estas substituições no código:

  • Substitua <yourConnectionString> pela cadeia de conexão.
  • Substitua <emailalias@emaildomain.com> pelo endereço de email para o qual deseja enviar uma mensagem.
  • Substitua <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> pelo endereço MailFrom do domínio verificado.

O comando acima também executa uma sondagem na messageId e retorna o status da entrega de email. O status pode ser um dos seguintes:

Nome do 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.

Parâmetros opcionais

Os parâmetros opcionais a seguir estão disponíveis na CLI do Azure.

  • O --html pode ser usado em vez do --text para o corpo do email HTML.

  • O --importance define o tipo de importância do email. Os valores conhecidos são: alto, normal e baixo. O padrão é o normal.

  • --to define a lista de destinatários de email.

  • O --cc define os endereços de email de cópia carbono.

  • O --bcc define os endereços de email de cópia oculta.

  • O --reply-to define o endereço de email de resposta.

  • O --disable-tracking indica se o rastreamento da participação do usuário deve ser desabilitado para esta solicitação.

  • O --attachments define a lista de anexos de email.

  • O --attachment-types define a lista de tipos de anexos de email, na mesma ordem dos anexos.

Além disso, você pode usar uma lista de destinatários com --cc e --bcc semelhante a --to. Precisa haver pelo menos um destinatário em --to ou --cc ou --bcc.

Comece a usar os Serviços de Comunicação do Azure usando a biblioteca de clientes de email do C# dos Serviços de Comunicação para enviar mensagens por 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);

Observação

Recomenda-se usar a sondagem manual (Enviar Email com sondagem de status assíncrona) para enviar emails.

Envio de e-mail básico

Construir sua mensagem de e-mail

Para enviar uma mensagem de e-mail, você precisa:

  • Definir o assunto e corpo do e-mail.
  • Definir o endereço do remetente. Construir sua mensagem de email com suas informações do Remetente que você obtém seu endereço MailFrom do seu domínio verificado.
  • Definir o Endereço do Destinatário.
  • Chame o método SendAsync. Adicione este código ao final do método Main no Program.cs:

Substituir por seus detalhes de domínio e modificar o conteúdo, detalhes do destinatário, conforme necessário


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

Enviar e obter 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.

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

Comece a usar os Serviços de Comunicação do Azure usando a biblioteca de clientes de email do JS dos Serviços de Comunicação para enviar mensagens por 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 JavaScript.

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 dos conteúdos 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. E-mail 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.
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).
EmailSendStatus Essa classe representa o conjunto de status de uma operação de envio de e-mail.

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

Nome do Status Descrição
Isstarted Retornará verdadeiro se a operação de envio de e-mail estiver em andamento e estiver sendo processada.
IsCompleted Retorna true se a operação de envio de e-mail tiver sido concluída sem erro e o e-mail estiver 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
result Propriedade que existe se a operação de envio de e-mail for concluída.
erro Propriedade que existe se 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 uma janela de terminal ou de comando, execute node --version para verificar se o Node.js está instalado.
  • Para exibir os domínios verificados com 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.

Configurar o ambiente do aplicativo

Criar um aplicativo Node.js

Primeiro, abra a janela de comando ou do terminal para criar um diretório para seu aplicativo e navegue até ele.

mkdir email-quickstart && cd email-quickstart

Execute npm init -y para criar um arquivo package.json com as configurações padrão.

npm init -y

Use um editor de texto para criar um arquivo chamado send-email.js no diretório raiz do projeto. Altere a propriedade "main" em package.json para "send-email.js". A seção a seguir demonstra como adicionar o código-fonte para este início rápido ao arquivo recém-criado.

Instalar o pacote

Use o comando npm install para instalar a biblioteca de clientes de Email dos Serviços de Comunicação do Azure para JavaScript.

npm install @azure/communication-email --save

A opção --save lista a biblioteca como uma dependência no arquivo package.json.

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

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

Importe o EmailClient da biblioteca de clientes e crie uma instância dele com sua cadeia de conexão.

O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING usando o pacote dotenv. Use o comando npm install para instalar o pacote dotenv. Saiba como gerenciar a cadeia de conexão do seu recurso.

npm install dotenv

Adicione o seguinte código 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 simplificar, este guia de início rápido usa cadeias de conexão, mas em ambientes de produção, recomenda-se o uso de entidades de serviço.

Envio de e-mail básico

Enviar uma mensagem de email

Para enviar um e-mail, busque a beginSend função do EmailClient. Esse método retorna um sondador que verifica o status da operação e recupera o resultado depois que ele é concluído.


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

Faça estas substituições no código:

  • Substitua <emailalias@emaildomain.com> pelo endereço de email para o qual deseja enviar uma mensagem.
  • Substitua <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> pelo endereço MailFrom do domínio verificado.

Executar o código

use o comando node para executar o código que você adicionou ao arquivo send-email.js.

node ./send-email.js

Código de exemplo

É possível baixar o aplicativo de exemplo do GitHub

Comece a usar os Serviços de Comunicação do Azure usando o SDK de Email dos Serviços de Comunicação para Java a fim de 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 do SDK de Email dos Serviços de Comunicação do Azure para Python.

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 interface cria um anexo de email aceitando uma ID exclusiva, uma cadeia de caracteres de tipo MIME de anexo de email, uma cadeia de caracteres de bytes de conteúdo e uma ID de conteúdo opcional para defini-la 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.
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.
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).
EmailSendStatus Essa classe representa o conjunto de status de uma operação de envio de e-mail.

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

Nome do Status Descrição
NOT_STARTED Não estamos enviando esse status de nosso serviço no momento.
IN_PROGRESS A operação de envio de e-mail está em andamento e está sendo processada.
SUCCESSFULLY_COMPLETED 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
FAILED 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 Adicionar domínios verificados personalizados para E-mail Serviço de Comunicação.

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute mvn -v para verificar se o Maven está instalado.
  • Para ver os domínios verificados com o recurso dos Serviços de Comunicação por Email, entre no portal do Azure. Localize o recurso dos Serviços de Comunicação por Email e abra a guia Provisionar domínios no painel de navegação à esquerda.

Configurar o ambiente do aplicativo

Para configurar um ambiente para o envio de emails, siga as etapas das seções a seguir.

Criar um aplicativo Java

Abra o terminal ou a janela de comando e navegue até o diretório no qual você deseja criar o seu aplicativo Java. Execute o comando abaixo para gerar o projeto Java a partir do modelo 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"

A meta generate cria um diretório com o mesmo nome do valor artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o diretório src/test/java contém a fonte de teste e o arquivo pom.xml é o POM (Modelo de Objeto do Projeto) do projeto.

Instalar o pacote

Abra o arquivo pom.xml no seu editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências.

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

Configurar o framework de aplicativos

Abra /src/main/java/com/communication/quickstart/App.java em um editor de texto, adicione diretivas de importação e remova a instrução 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.*;

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

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

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

Para autenticar um cliente, crie uma instância de EmailClient com sua cadeia de conexão. Saiba como gerenciar a cadeia de conexão do seu recurso. Também é possível criar uma instância do cliente com qualquer cliente HTTP personalizado que implemente a interface com.azure.core.http.HttpClient.

Para criar uma instância de um cliente síncrono, adicione o seguinte código ao 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 criar uma instância de um cliente assíncrono, adicione o seguinte código ao 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>";

EmailAsyncClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

Para simplificar, este guia de início rápido usa cadeias de conexão, mas em ambientes de produção, recomenda-se o uso de entidades de serviço.

Envio de e-mail básico

Uma mensagem de email pode ser criada usando o objeto EmailMessage no SDK.

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

Faça estas substituições no código:

  • Substitua <emailalias@emaildomain.com> pelo endereço de email para o qual deseja enviar uma mensagem.
  • Substitua <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> pelo endereço MailFrom do domínio verificado.

Para enviar um e-mail, chame a função beginSend do EmailClient.

Chamar beginSend no cliente síncrono retorna um objeto SyncPoller, que pode ser usado para verificar o status da operação e recuperar o resultado após a conclusão. Observe que a solicitação inicial para enviar um email será enviada assim que o método beginSend for chamado. Enviar um email é uma operação de execução prolongada. É importante observar que o método getFinalResult() no sondador é uma operação de bloqueio até que um estado terminal (SUCCESSFULLY_COMPLETED ou FAILED) seja atingido. O método recomendado é fazer sondagem manual em um intervalo apropriado para suas necessidades de aplicativo, conforme demonstrado no exemplo abaixo.

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null); // This will send out the initial request to send an email

    PollResponse<EmailSendResult> pollResponse = null;

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

    // Polling is done manually to avoid blocking the application in case of an error
    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());
}

Executar o código

  1. Acesse o diretório que contém o arquivo pom.xml e compile o projeto usando o comando mvn.

    mvn compile

  2. Crie o pacote.

    mvn package

  3. Execute o comando mvn a seguir para executar o aplicativo.

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

Código de exemplo

É possível baixar o aplicativo de exemplo do GitHub

Comece a usar os Serviços de Comunicação do Azure usando o SDK de Email dos Serviços de Comunicação para Python a fim de 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

O objeto de resposta e modelo de mensagem JSON a seguir demonstra alguns dos principais recursos do SDK de Email dos Serviços de Comunicação do Azure 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.
    }
}

Os response.status valores são explicados ainda mais na tabela a seguir.

Nome do Status Descrição
InProgress 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 em uma janela de comando, execute o comando python --version para verificar se o Python está instalado.
  • Para ver os domínios verificados com o recurso dos Serviços de Comunicação por Email, entre no portal do Azure. Localize o recurso dos Serviços de Comunicação por Email e abra a guia Provisionar domínios no painel de navegação à esquerda.

Configurar o ambiente do aplicativo

Para configurar um ambiente para o envio de emails, siga as etapas das seções a seguir.

Criar um novo aplicativo Python

  1. Abra o terminal ou a janela Comando. Em seguida, use o comando a seguir para criar um ambiente virtual e ativá-lo. Esse comando cria um novo diretório para seu aplicativo.

    python -m venv email-quickstart

  2. Navegue até o diretório raiz do ambiente virtual e ative-o usando os comandos a seguir.

    cd email-quickstart
.\Scripts\activate

  3. Use um editor de texto para criar um arquivo chamado send-email.py no diretório raiz do projeto e adicione a estrutura do programa, incluindo o tratamento de exceção básico.

    import os
from azure.communication.email import EmailClient

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

Nas seções a seguir, você adicionará todo o código-fonte deste guia de início rápido ao arquivo send-email.py que acabou de criar.

Instalar o pacote

Ainda no diretório do aplicativo, instale o pacote do SDK de Email dos Serviços de Comunicação do Azure para Python usando o comando a seguir.

pip install azure-communication-email

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

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

Crie uma instância de um EmailClient com a cadeia de conexão. Saiba como gerenciar a cadeia de conexão do seu recurso.

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

Para simplificar, este guia de início rápido usa cadeias de conexão, mas em ambientes de produção, recomenda-se o uso de entidades de serviço.

Envio de e-mail básico

Enviar uma mensagem de email

Para enviar uma mensagem de e-mail, você precisa:

  • Construa a mensagem com os seguintes valores:
    • senderAddress: Um endereço de e-mail de remetente válido, encontrado no campo MailFrom no painel de visão geral do domínio vinculado ao recurso dos Serviços de Comunicação E-mail.
    • recipients: um objeto com uma lista de destinatários de email e, opcionalmente, listas de destinatários de email em CC e CCO.
    • content: Um objeto que contém o assunto e, opcionalmente, o texto sem formatação ou conteúdo HTML de uma mensagem de e-mail.
  • Acione o método begin_send, que retorna o resultado da operação.
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())

Faça estas substituições no código:

  • Substitua <emailalias@emaildomain.com> pelo endereço de email para o qual deseja enviar uma mensagem.
  • Substitua <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> pelo endereço MailFrom do domínio verificado.

Obter o status da entrega de email

Podemos sondar o status da entrega de e-mail definindo um loop no objeto de status da operação retornado do método eEmailClientbegin_send:

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)

Executar o código

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

python send-email.py

Código de exemplo

É possível baixar o aplicativo de exemplo do GitHub

Pré-requisitos

Enviar email

Para adicionar uma nova etapa ao fluxo de trabalho usando o conector de email dos Serviços de Comunicação do Azure, siga estas etapas:

  1. No designer, abra o fluxo de trabalho do aplicativo lógico.

    Consumo

    1. Na etapa em que você deseja adicionar a nova ação, selecione Nova etapa. Como alternativa, para adicionar a nova ação entre as etapas, mova o ponteiro sobre a seta entre essas etapas, selecione o sinal de adição (+) e selecione Adicionar uma ação.

    2. Na caixa de pesquisa Escolha uma operação, selecione Premium. Na caixa de pesquisa, insira Email de Comunicação do Azure.

    3. Na lista de ações, selecione Enviar email.

      Captura de tela que mostra o conector de Email dos Serviços de Comunicação do Azure, ação Enviar email.

    Standard

    1. Na tapa em que você deseja adicionar a nova ação, selecione o sinal de adição (+). Como alternativa, para adicionar a nova ação entre as etapas, mova o ponteiro sobre a seta entre essas etapas, selecione o sinal de adição (+) e selecione Adicionar uma ação.

    2. Na caixa de pesquisa Adicionar uma ação, selecione Premium na lista de seleção do runtime. Na caixa de pesquisa, insira Email de Comunicação do Azure.

    3. Na lista de ações, selecione Enviar email.

  2. Forneça um nome para a conexão.

  3. Insira a cadeia de conexão para o recurso do Serviço de Comunicações do Azure. Para localizar essa cadeia de caracteres, siga estas etapas:

    1. No portal do Azure, abra o recurso do Serviço de Comunicação do Azure.

    2. No menu de recursos, em Configurações, selecione Chaves e copie a cadeia de conexão.

      Captura de tela que mostra a Cadeia de Conexão dos Serviços de Comunicação do Azure.

  4. Quando terminar, selecione Criar.

  5. No campo De, use o endereço de email que você configurou nos pré-requisitos. Insira os valores dos campos Para Email, Assunto e Corpo, por exemplo:

    Captura de tela que mostra o conector de Email dos Serviços de Comunicação do Azure, entrada de ação Enviar email.

  6. Salve seu fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Testar seu fluxo de trabalho

Com base no consumo ou no fluxo de trabalho Standard, inicie manualmente o fluxo de trabalho:

  • Consumo: Na barra de ferramentas do designer, escolha Executar gatilho>Executar.
  • Standard: No menu de fluxo de trabalho, selecione Visão geral. Na barra de ferramentas, escolha Executar gatilho>Executar.

O fluxo de trabalho cria um usuário, emite um token de acesso para esse usuário e, em seguida, remove e exclui o usuário. Você pode verificar as saídas dessas ações, depois que o fluxo de trabalho for executado com êxito.

Você deve receber um email no endereço especificado. Além disso, você pode usar a ação Obter status da mensagem de email para verificar o status dos emails enviados por meio da ação Enviar email. Para ver mais ações, revise a documentação do conector de email dos Serviços de Comunicação do Azure.

Limpar recursos de fluxo de trabalho

Para limpar o recurso do aplicativo lógico, o fluxo de trabalho e os recursos relacionados, examine como limpar recursos do aplicativo lógico de Consumo ou como limpar recursos do aplicativo lógico Standard.

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

Para 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 quaisquer outros recursos associados. Saiba mais sobre como limpar recursos.

Próximas etapas

Neste início rápido, você aprendeu a enviar emails usando os Serviços de Comunicação do Azure. Talvez seja necessário também: