Utilize o Azure para enviar e-mails com SendGrid, Graph e Office 365 – techsyncer

A Microsoft Azure não possui um serviço de entrega de e-mails. Seja para testar aplicativos ou desenvolver scripts no Azure para enviar e-mails, saiba que não há um serviço de e-mail nativo disponível para você.

A conexão SMTP de saída via porta 25 também é completamente bloqueada no Azure. Se você for um cliente empresarial, pode solicitar o desbloqueio da porta 25 para seu locatário do Azure. Caso contrário, como mais você pode enviar e-mails a partir do Azure?

Geralmente, existem duas maneiras de permitir o envio de e-mails pelo Azure: usando um host inteligente SMTP e requerimentos da API REST. A maioria dos serviços de entrega de e-mails oferece métodos tanto de SMTP quanto de API para enviar e-mails. Neste artigo, você aprenderá como enviar e-mails do Azure para o resto do mundo.

Pré-requisitos

Este artigo é um guia prático, e se você planeja seguir os exemplos conforme eles avançam, há alguns requisitos que você deve atender.

Uma assinatura do Azure. Você pode se inscrever para uma assinatura gratuita do Azure se ainda não tiver uma.
Um Máquina Virtual Azure (VM). Consulte Criar uma máquina virtual Windows no portal Azure para aprender como criar uma nova VM se ainda não tiver uma.
O Windows PowerShell 5.1 ou o PowerShell 7.1 são necessários.
A valid sender email address. Using a free email address domain, such as gmail.com, is not recommended. As much as possible, use a sender email address that uses a domain that you own.

Saber quais serviços de e-mail usar com o Azure para enviar e-mails

Há vários serviços de e-mail na nuvem disponíveis para uso. Alguns dos nomes proeminentes são SendGrid, MailJet e MailGun. Independentemente do serviço de e-mail escolhido, o processo de envio de e-mails pelo Azure é semelhante; endereço do servidor e porta para SMTP e endereço do ponto de extremidade da API para REST.

SendGrid é um exemplo de serviço de e-mail de terceiros usado neste artigo. Outros serviços de e-mail usados como exemplos incluem Relé SMTP do Office 365 e Microsoft Graph API.

Relacionado: Qual serviço de e-mail do Azure escolher para 2021

Usando o SendGrid

O SendGrid é provavelmente a opção de serviço de e-mail mais popular para enviar e-mails do Azure. Azure e SendGrid são tão populares porque costumava haver um plano gratuito com limite de 25.000 e-mails por mês para os clientes do Azure.

Embora o plano gratuito não esteja mais sendo oferecido no portal do Azure, como confirmado pela Microsoft, é possível se inscrever para uma assinatura gratuita com limite de 100 e-mails por dia. Em seguida, você terá acesso ao serviço de relé SMTP do SendGrid ou à API de e-mail para enviar e-mails de um aplicativo ou VM do Azure.

Criando uma Conta SendGrid

Usar os serviços do SendGrid requer que você tenha uma conta SendGrid primeiro. Vá para a página de registro e você deverá ver o formulário conforme mostrado abaixo. Insira seu endereço de e-mail e sua senha escolhida. Em seguida, aceite os termos e clique no botão Criar Conta.

Na próxima página, você precisa inserir seu nome e informações da empresa. Você também precisa selecionar as opções apropriadas, como seu cargo, e-mails para enviar por mês e o número de funcionários. Em seguida, clique em Começar.

Ao fazer o login inicial no SendGrid, você pode receber um erro dizendo: “Você não está autorizado a acessar o SendGrid; por favor, entre em contato com o Suporte.” Quando isso acontecer, abra um chamado com o suporte do SendGrid. Eles podem precisar fazer algumas perguntas de verificação antes de desbloquear seu acesso.

Você será solicitado a ativar a autenticação de dois fatores durante o primeiro login. Certifique-se de seguir as instruções com precisão.

Criando uma Identidade de Remetente no SendGrid

Após criar a conta no SendGrid, o próximo passo é autorizar a identidade do remetente. Existem duas opções; autenticar um único remetente (por exemplo, [email protected]) ou autenticar um domínio inteiro (por exemplo, dominio.com).

Neste exemplo, você criará uma única identidade de remetente que servirá como seu endereço de remetente. Somente o endereço de remetente verificado poderá enviar mensagens através do serviço do SendGrid. Siga as instruções abaixo para criar a identidade de remetente única.

Na página de Boas-vindas, clique no botão Criar um Único Remetente.

2. Em seguida, na expansão Criar um Remetente, forneça todas as informações necessárias. Os campos obrigatórios estão marcados com um asterisco vermelho ao lado para facilitar a referência. Após inserir os detalhes, clique em Criar.

Em seguida, você verá o novo endereço do remetente listado na página de Verificação de Remetente Único. Como você pode ver no exemplo abaixo, o endereço ainda não está verificado, como indicado por um X vermelho na coluna VERIFICADO.

Viewing the sender address verification status

3. Para verificar o remetente, localize o e-mail enviado para o endereço do remetente, semelhante à captura de tela abaixo. Em seguida, clique no botão Verificar Remetente Único.

O endereço do remetente será verificado. Você deve ver uma página semelhante, como mostrado abaixo, confirmando que a verificação do remetente está completa.

Confirming that the sender address verification is complete

Criando uma Chave de API SendGrid

Depois de criar o endereço do remetente único, a interface para criar chaves de API fica disponível. Pense na chave de API do SendGrid como a senha. Sem ela, seu código não pode autenticar com o serviço de retransmissão SMTP do SendGrid. Siga as etapas abaixo para criar uma nova chave de API.

No menu do lado esquerdo, clique em Configurações > Chaves de API. Em seguida, clique no botão Criar Chave de API no canto superior direito da página.

2. A janela Criar Chave de API aparece. Digite o nome da chave de API que você está criando. Use um nome que faça sentido, como “Chave de API de Teste Azure.” Em seguida, para simplificar, selecione Acesso Completo como permissão. Por fim, clique no botão Criar & Visualizar.

Naming the API key and choosing permissions

3. A nova Chave de API é mostrada a seguir. Agora copie e salve o valor da chave, pois ela não será mostrada novamente. Após copiar a chave, clique em Concluído.

Enviando um E-mail do Azure usando o Serviço de Retransmissão SMTP do SendGrid

Agora você tem os componentes necessários (conta, remetente e chave) para usar o SendGrid para enviar emails do Azure. É hora de testar se o serviço de retransmissão SMTP do SendGrid funciona. Nesta seção, você vai usar o PowerShell para enviar emails de uma VM do Azure.

Antes de executar qualquer código, você deve conhecer esses requisitos.

O endereço do servidor SMTP do SendGrid é smtp.sendgrid.net.
O nome de usuário usado para autenticação SMTP é sempre apikey.
A senha a ser usada é o valor da chave de API que você criou no SendGrid.
Não use a porta 25. Use a porta 587 em vez disso.
Apenas o endereço de remetente verificado no SendGrid é válido para usar como remetente dos seus emails. Neste exemplo, o remetente autorizado é [email protected].

O script abaixo enviará um email através do relé SMTP do SendGrid. Copie o código abaixo e altere os valores de $sendGridApiKey, From, To e Body. Em seguida, execute o código em sua sessão do PowerShell. Consulte os comentários para entender o que cada linha de código faz.

# Defina sua chave de API aqui
$sendGridApiKey = 'SG...........P258'

$SendGridEmail = @{
	# Use seu endereço de remetente verificado.
	From = '[email protected]'
	# Especifique o destinatário do e-mail. Qualquer endereço de e-mail válido deve funcionar.
	To = '[email protected]'
	# Atualize isso com o assunto do e-mail que você deseja usar.
	Subject = 'This is a test message from Azure via SendGrid'
	# Atualize isso com o corpo ou mensagem do e-mail que você deseja enviar.
	Body = 'This is a test message from Azure via SendGrid'
	
	# NÃO ALTERE NADA ABAIXO DESTA LINHA
	SmtpServer = 'smtp.sendgrid.net'
	Port = 587
	UseSSL = $true
	Credential = New-Object PSCredential 'apikey', (ConvertTo-SecureString $sendGridApiKey -AsPlainText -Force)	
}

# Envie o e-mail
Send-MailMessage @SendGridEmail

A demonstração abaixo mostra como seria executar o código acima no PowerShell em tempo real.

Sending an Email from Azure using SendGrid SMTP Relay

Para confirmar a entrega do e-mail, verifique a caixa de correio do destinatário para encontrar a mensagem de teste que você enviou. O resultado seria semelhante ao mostrado abaixo. Como você pode ver, a mensagem veio do endereço do remetente via sendgrid.net.

Confirming the SMTP test message was delivered

Relacionado: Send-MailMessage: O Caminho PowerShell para Enviar E-mail

Enviando um E-mail do Azure usando a API do SendGrid

Outra maneira de usar o SendGrid com o Azure para enviar e-mails é usando a API Web V3 do SendGrid. Em vez de se comunicar com o SendGrid via SMTP, o uso da API ocorre por meio do HTTP. A solicitação HTTP é enviada para a URL do ponto de extremidade da API do SendGrid.

O script de exemplo em PowerShell abaixo utiliza o cmdlet Invoke-RestMethod para enviar a solicitação de e-mail do Azure para o SendGrid. Copie o código e altere os valores das variáveis $sendGridApiKey, $fromAddress, $toAddress, $mailSubject e $mailMessage.

Quando terminar de atualizar as variáveis, execute o código no PowerShell.

Set your API Key here
 $sendGridApiKey = 'SG………..P258'
 Set the sender and recipient addresses
 $fromAddress = "[email protected]"
 $toAddress = "[email protected]"
 Set the mail subject
 $mailSubject = "This is a test message from Azure via SendGrid API"
 Set the mail message
 $mailMessage = "This is a test message from Azure via SendGrid API"
 DO NOT CHANGE ANYTHING BELOW THIS LINE
 Compose the Mail Body
 $mailbody = @{
   personalizations = @(
     @{
       to      = @(
         @{
           email = $toAddress
         }
       )
       subject = $mailSubject
     }
   )
   from             = @{
     email = $fromAddress
   }
   content          = @(
     @{
       type  = "text/plain"
       value = $mailMessage
     }
   )
 } | ConvertTo-Json -Depth 10
 $headers = @{'Authorization' = "Bearer $($sendGridApiKey)" }
 $mailApiUri = 'https://api.sendgrid.com/v3/mail/send'
 Send the email
 Invoke-RestMethod -Method Post -Uri $mailApiUri -Body $mailbody -Headers $headers -ContentType application/json

Após executar o código PowerShell acima, verifique a caixa de correio do destinatário e confirme que recebeu a mensagem de teste. O exemplo abaixo mostra uma mensagem de teste entregue com sucesso do Azure via API SendGrid.

Confirming the API test message was delivered

Se desejar saber mais sobre a API Web do SendGrid, visite a página V3 Mail Send API.

Usando Autenticação SMTP do Office 365

Outra opção para enviar e-mails do Azure é usar o relay SMTP do Office 365. Isso é válido se sua organização já tiver uma assinatura do Exchange Online. Assim como ao usar o SendGrid como um host inteligente SMTP, o relay SMTP do Office 365 exige autenticação e o uso apenas da porta 587.

Antes de usar o relay SMTP do Office 365, você deve estar ciente das seguintes condições para que funcione.

O endereço do remetente deve ser um objeto de destinatário válido do Exchange Online, como uma caixa de correio ou um usuário de e-mail. No entanto, se os recibos de não entrega (NDR) precisarem ser armazenados, use uma caixa de correio.
O usuário de autenticação deve ter uma licença válida do Exchange Online. Apenas usuários licenciados do Exchange Online têm permissão para usar o relay SMTP do Office 365.
Suponha que o usuário de autenticação seja diferente do remetente. Nesse caso, o usuário deve ser atribuído a permissão de Enviar como para a conta do remetente.
O método de autenticação utilizado é básico (legado). Isso significa que se a autenticação básica do SMTP estiver desativada em sua organização ou quando a Microsoft finalmente descontinuar a autenticação básica, a autenticação SMTP não funcionará mais.
O endereço do servidor de retransmissão SMTP é smtp.office365.com, e o número da porta é 587.

Relacionado: Como Enviar E-mails com o Office 365 Direct Send e PowerShell

Criando um Endereço de Remetente do Office 365

Neste exemplo, o remetente e o usuário de autenticação são distintos. Certifique-se de conectar ao Exchange Online PowerShell primeiro. Uma vez conectado, siga as etapas abaixo.

Crie uma caixa de correio compartilhada usando o comando abaixo. Altere os valores de -Name e -PrimarySMTPAddress de acordo com os seus valores corretos.

New-Mailbox -Shared -Name 'SMTP Mailer 365' -PrimarySMTPAddress '[email protected]'

A caixa de correio compartilhada deve ser criada e retornará um resultado semelhante ao mostrado abaixo.

Creating a new shared mailbox as the sender

Em seguida, atribua a permissão Enviar Como ao usuário de autenticação. No exemplo abaixo, o usuário recebe a permissão Enviar Como na caixa de correio compartilhada.

Add-RecipientPermission -Identity '[email protected]' -Trustee '[email protected]' -AccessRights SendAs -Confirm:$false

Depois que o comando acima for executado, você deve obter um resultado semelhante ao mostrado abaixo.

Enviando um Email do Azure usando o Relé SMTP do Office 365

Após a criação do endereço do remetente e a atribuição da permissão Enviar Como, o próximo passo é testar a entrega do email usando o PowerShell e o relé SMTP do Office 365.

O código abaixo autentica usando [email protected]. O endereço [email protected] aparece como o remetente. Certifique-se de atribuir seus valores corretos antes de executar o código.

# Fornecer suas credenciais SMTP
$username = '[email protected]'
$password = '*************'

# Fornecer o endereço de email do remetente e do destinatário
$fromAddress = '[email protected]'
$toAddress = '[email protected]'

# Especificar o assunto do email e a mensagem
$mailSubject = 'This is a test message from Azure via Office 365 SMTP Relay'
$mailMessage = 'This is a test message from Azure via Office 365 SMTP Relay'

# NÃO ALTERAR NADA ABAIXO DESTA LINHA
$Office365RelayEmail = @{
	From = $fromAddress
	To = $toAddress
	Subject = $mailSubject
	Body = $mailMessage	
	SmtpServer = 'smtp.office365.com'
	Port = 587
	UseSSL = $true
	Credential = New-Object PSCredential $username, (ConvertTo-SecureString $password -AsPlainText -Force)	
}

# Enviar o email
Send-MailMessage @Office365RelayEmail

O uso de credenciais em scripts que estão em texto simples não é recomendado. Scripts de produção devem usar criptografia de credenciais ou gerenciamento de segredos para proteger nomes de usuário e senhas.

Agora é hora de verificar a caixa de correio do destinatário. Confirme se a mensagem de teste foi recebida.

Confirming the Office 365 SMTP relay test message was delivered

Usando a API do Microsoft Graph para Enviar Email do Azure

Em vez de usar o relay SMTP do Office 365, a maneira mais segura e recomendada é usar a API Microsoft Graph. Com a API do Microsoft Graph, você pode enviar emails de qualquer caixa de correio em sua organização usando chamadas de API REST.

Para usar a API do Microsoft Graph para enviar emails, é necessário um aplicativo registrado no Azure AD. O aplicativo registrado deve ser atribuído com a permissão de API Mail.Send. As seções a seguir mostrarão como configurar a API do Microsoft Graph e usá-la para enviar emails.

Relacionado: Usando a API do Microsoft Graph com PowerShell

Registrando um Novo Aplicativo no Azure Active Directory

Nesta seção, você registrará um novo aplicativo da web no diretório ativo do Azure. O novo aplicativo age como a identidade de autenticação para o Microsoft Graph. Faça login no Azure Portal se ainda não tiver feito.

Acesse Azure Active Directory —> Registro de aplicativos. Em seguida, clique no botão Novo registro.

2. Na página Registrar um aplicativo, insira o nome do aplicativo.

3. Sob o Tipos de conta suportados, escolha Contas apenas neste diretório organizacional. Digite HTTP://localhost como URI de Redirecionamento. Por fim, clique no botão Registrar.

4. Aguarde o registro ser concluído. O processo leva apenas alguns segundos. Não se esqueça de anotar o ID da Aplicação (cliente) resultante e os valores do ID do Diretório (locatário). Você precisará deles posteriormente.

Saving the Application ID and Directory values

Criando uma Chave Secreta do Cliente

Considere o ID da aplicação criado na seção anterior como o nome de usuário. E esse ID de aplicativo precisa de uma senha – que é a chave secreta.

Para adicionar uma nova chave secreta do aplicativo, siga as etapas abaixo.

Vá para Certificados e segredos, clique em Nova chave secreta do cliente.
Insira a descrição para a chave secreta do cliente, como chave1.
Selecione quando a chave secreta expira e clique em Adicionar. No exemplo abaixo, a chave secreta expira em 1 ano.

Você verá a nova chave listada na seção de Segredos do cliente. Este é o único momento em que você verá o valor da chave, então salve uma cópia.

Agora que você criou o ID da aplicação e a chave secreta, o que resta é atribuir as permissões necessárias da API do Microsoft Graph. Sem atribuir permissão, a aplicação pode autenticar, mas não terá autoridade para fazer nada, como enviar e-mails.

Para começar a atribuir permissões, siga as etapas abaixo.

Clique em Permissões da API no menu do lado esquerdo.

2. Em seguida, na página de Permissões Configuradas, clique no botão Adicionar uma permissão.

3. No painel Solicitar permissões da API, clique para selecionar API do Microsoft Graph.

4. Quando solicitado a escolher o tipo de permissão necessária para a aplicação, clique em Permissões da aplicação.

5. Na caixa de pesquisa, digite Mail.Send para procurá-la. No resultado, clique para marcar a permissão Mail.Send. Por fim, clique em Adicionar permissões.

6. Você perceberá que o status da permissão é “Não concedida para <nome da organização>.” Neste ponto, você ou um administrador global deve primeiro conceder consentimento para a aplicação. Para conceder permissão, clique no botão Conceder consentimento de administrador para <organização>.

O status da permissão da API então muda para “Concedida para <nome da organização>“.

Obtendo um Token de Acesso

As solicitações enviadas à API do Microsoft Graph requerem um token de acesso. Neste ponto, você já possui o ID da aplicação, a chave secreta e o ID do locatário. Essas três informações são necessárias para adquirir um token de acesso.

O script PowerShell abaixo envia a solicitação de token de acesso para o ponto de extremidade da API do Microsoft Graph. Você deve atualizar os valores de $client_id, $client_secret e $tenant_id para seus valores corretos primeiro. Em seguida, copie e cole o código no PowerShell para solicitar o token de acesso.

# substitua pelo ID de sua aplicação
$client_id = 'APPLICATION ID'
# substitua pela chave secreta
$client_secret = 'SECRET KEY'
# substitua pelo ID do seu locatário
$tenant_id = 'TENANT ID'

# NÃO ALTERE NADA ABAIXO DESTA LINHA
$request = @{
        Method = 'POST'
        URI    = "https://login.microsoftonline.com/$tenant_id/oauth2/v2.0/token"
        body   = @{
            grant_type    = "client_credentials"
            scope         = "https://graph.microsoft.com/.default"
            client_id     = $client_id
            client_secret = $client_secret
        }
    }
# Obtenha o token de acesso
$token = (Invoke-RestMethod @request).access_token
# visualize o valor do token
$token

A demonstração abaixo mostra o script do PowerShell em ação. Observe que o token de acesso solicitado é armazenado na variável $token.

Os tokens de acesso são válidos por apenas uma (1) hora a partir do momento em que foram adquiridos. Você precisará solicitar outro token de acesso após a expiração do token anterior.

Enviando um Email do Azure usando a Microsoft Graph API

Agora você está pronto para usar a Microsoft Graph API com o Azure para

# Fornecer o endereço de e-mail do remetente e do destinatário
$fromAddress = 'SENDER ADDRESS HERE'
$toAddress = 'RECIPIENT ADDRESS HERE'

# Especifique o assunto do e-mail e a mensagem
$mailSubject = 'This is a test message from Azure via Microsoft Graph API'
$mailMessage = 'This is a test message from Azure via Microsoft Graph API'

# NÃO ALTERE NADA ABAIXO DESTA LINHA
# Construir a solicitação da API Microsoft Graph
$params = @{
  "URI"         = "https://graph.microsoft.com/v1.0/users/$fromAddress/sendMail"
  "Headers"     = @{
    "Authorization" = ("Bearer {0}" -F $token)
  }
  "Method"      = "POST"
  "ContentType" = 'application/json'
  "Body" = (@{
    "message" = @{
      "subject" = $mailSubject
      "body"    = @{
        "contentType" = 'Text'
        "content"     = $mailMessage
      }
      "toRecipients" = @(
        @{
          "emailAddress" = @{
            "address" = $toAddress
          }
        }
      )
    }
  }) | ConvertTo-JSON -Depth 10
}

# Enviar a mensagem
Invoke-RestMethod @params -Verbose