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

Brazilian Portuguese
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 através da porta 25 é completamente bloqueada no Azure também. Se você for um cliente empresarial, pode solicitar o desbloqueio da porta 25 para o seu locatário do Azure. Caso contrário, como mais você pode enviar e-mails do Azure?

Normalmente, existem duas maneiras de permitir que e-mails de saída passem pelo Azure; usando um host inteligente SMTP e solicitações API REST. A maioria dos serviços de entrega de e-mails oferece ambos os métodos, SMTP e API, para enviar e-mails. Neste artigo, você aprenderá como enviar e-mails do Azure para o restante do mundo.

Pré-requisitos

Este artigo é um Guia Prático, e se você planeja seguir os exemplos à medida que 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.
Uma Máquina Virtual (VM) Azure. Consulte Criar uma máquina virtual Windows no portal do Azure para aprender como criar uma nova VM caso você ainda não tenha uma.
O Windows PowerShell 5.1 ou o PowerShell 7.1.
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 em nuvem disponíveis para uso. Alguns dos nomes proeminentes são SendGrid, MailJet e MailGun. Independentemente do serviço de e-mail escolhido, o uso deles para enviar e-mails do 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. Serviços de e-mail adicionais usados como exemplos são relé SMTP do Office 365 e Microsoft Graph API.

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

Usando o SendGrid

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 da Azure.

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

Criando uma Conta na SendGrid

Usar os serviços da SendGrid requer que você tenha uma conta na SendGrid primeiro. Vá para a página de inscrição e você verá o formulário como 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 a enviar por mês e o número de funcionários. Em seguida, clique em Começar.

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

Você será solicitado a habilitar a autenticação de dois fatores durante seu 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 identidade de remetente única que servirá como seu endereço de remetente. Apenas 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 de Criar um Remetente, forneça todas as informações necessárias. Os campos obrigatórios são marcados com um asterisco vermelho para facilitar a referência. Após inserir os detalhes, clique em Criar.

Você verá então 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 do SendGrid

Após 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-se 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 lateral Criar Chave de API aparece. Insira o nome da chave de API que você está criando. Use um nome que faça sentido, como “Chave de API de Teste do Azure“. Em seguida, para simplificar, selecione Acesso Completo como permissão. Por fim, clique no botão Criar e Visualizar.

Naming the API key and choosing permissions

3. A nova Chave de API é mostrada abaixo. Agora copie e salve o par chave-valor, pois ela não será exibida 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 e-mails 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 e-mails de uma VM do Azure.

Antes de executar qualquer código, você deve estar ciente desses 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 ser usado como remetente de seus e-mails. Neste exemplo, o remetente autorizado é [email protected].

O script abaixo enviará um e-mail através da retransmissão 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 do e-mail ou mensagem 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 a execução do código acima no PowerShell em tempo real.

Sending an Email from Azure using SendGrid SMTP Relay

Para confirmar a entregabilidade 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 do PowerShell para Enviar E-mails

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 o SendGrid Web API V3. Em vez de se comunicar com o SendGrid via SMTP, usar a API comunica-se usando HTTP. A solicitação HTTP é enviada para o URL do endpoint da API do SendGrid.

O exemplo de script PowerShell abaixo usa 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 se recebeu a mensagem de teste. O exemplo abaixo mostra uma mensagem de teste entregue com sucesso do Azure via API do SendGrid.

Confirming the API test message was delivered

Se você quiser saber mais sobre a API da 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 relé SMTP do Office 365. Isso é se sua organização já tiver uma assinatura do Exchange Online. Assim como usar o SendGrid como um smart host SMTP, o relé SMTP do Office 365 requer autenticação e o uso da porta 587 apenas.

Antes de usar o relé SMTP do Office 365, você deve conhecer as 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 correio. Mas, se os recibos de não entrega (NDR) devem 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 relé 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 com 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 abandonar a autenticação básica, o SMTP Auth deixará de funcionar.
O endereço do servidor de retransmissão SMTP é smtp.office365.com, e o número da porta é 587.

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

Criando um Endereço de Remetente no Office 365

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

Crie uma caixa de correio compartilhada usando o comando abaixo. Altere os valores -Name e -PrimarySMTPAddress conforme necessário.

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

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

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

Após a execução do comando acima, você deve obter um resultado semelhante ao abaixo.

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

Após a criação do endereço do remetente e atribuição da permissão de 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.

# Forneça suas credenciais SMTP
$username = '[email protected]'
$password = '*************'

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

# Especifique 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 ALTERE 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)	
}

# Envie 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ários 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 Microsoft Graph para Enviar Email do Azure

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

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

Relacionado: Usando a API Microsoft Graph com PowerShell

Registrando um Novo Aplicativo no Azure Active Directory

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

Navegue até 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 Tipo de conta suportado, escolha Contas apenas neste diretório organizacional. Digite HTTP://localhost como o 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 do Aplicativo (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 do aplicativo que você criou na seção anterior como o nome de usuário. E esse ID do 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, depois 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 Segredos do cliente. Agora é o único momento em que você verá o valor da chave, então salve uma cópia.

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

Para começar a atribuir permissão, 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 fly-out de Solicitar permissões da API, clique para selecionar Microsoft Graph API.

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á-lo. No resultado, clique para marcar a permissão Mail.Send. Por último, clique em Adicionar permissões.

6. Você notará que o status da permissão é “Não concedido 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 administrativo para <organização>.

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

Obtendo um Token de Acesso

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

O script do PowerShell abaixo envia a solicitação de token de acesso para o endpoint da Microsoft Graph API. Você deve atualizar o $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 do seu aplicativo
$client_id = 'APPLICATION ID'
# substitua pela sua chave secreta
$client_secret = 'SECRET KEY'
# substitua pelo seu ID de 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
        }
    }
# Obter o token de acesso
$token = (Invoke-RestMethod @request).access_token
# visualizar o valor do token
$token

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

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

Enviar um Email do Azure usando a API do Microsoft Graph

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

# Forneça 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
# Construa a solicitação da API do 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
}

# Envie a mensagem
Invoke-RestMethod @params -Verbose