Использование Azure для отправки электронной почты с помощью SendGrid, Graph и Office 365

Учебники

Microsoft Azure не имеет службы доставки электронной почты. Если вы тестируете приложения или разрабатываете скрипты в Azure для отправки электронной почты, знайте, что у вас нет доступа к нативной службе электронной почты.

Исходящее соединение SMTP через порт 25 также полностью блокируется в Azure. Если вы являетесь корпоративным клиентом, вы можете запросить разблокировку порта 25 для своего арендатора Azure. В противном случае, как еще можно отправлять электронные письма из Azure?

Обычно есть два способа пропуска исходящей почты через Azure: использование умного хоста SMTP и запросы через API REST. Большинство служб доставки электронной почты предлагают оба метода – SMTP и API – для отправки писем. В этой статье вы узнаете, как отправлять электронные письма из Azure во всем мире.

Предварительные требования

Эта статья является инструкцией, и если вы планируете следовать примерам по мере их выполнения, у вас должны быть выполнены некоторые требования.

  • Подписка Azure. Вы можете зарегистрироваться для получения пробной подписки Azure, если у вас еще ее нет.
  • Виртуальная машина Azure (VM). Обратитесь к Создание виртуальной машины Windows в портале Azure, чтобы узнать, как создать новую виртуальную машину, если у вас еще ее нет.
  • Windows PowerShell 5.1 или 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.

Как выбрать электронную почту для использования с Azure для отправки писем

Существует несколько облачных почтовых сервисов, которые можно использовать. Некоторые из известных названий – SendGrid, MailJet и MailGun. Независимо от выбранного почтового сервиса, использование их для отправки писем из Azure аналогично: адрес сервера и порт для SMTP и адрес конечной точки API для REST.

SendGrid – это пример стороннего почтового сервиса, используемого в этой статье. Дополнительные примеры почтовых сервисов, используемых в статье, – это SMTP-ретрансляция Office 365 и Microsoft Graph API.

Связано: Какой почтовый сервис Azure выбрать в 2021 году

Использование SendGrid

SendGrid вероятно, самый популярный вариант сервиса электронной почты для отправки писем из Azure. Azure и SendGrid так популярны, потому что раньше был предложен бесплатный тарифный план с ограничением в 25 000 писем в месяц для клиентов Azure.

Хотя бесплатный тарифный план больше не предлагается в портале Azure, как подтверждено Microsoft, вы можете зарегистрироваться для получения бесплатной подписки с ограничением в 100 писем в день. Затем у вас будет доступ к ретрансляционному сервису SMTP или API электронной почты SendGrid для отправки писем из приложения или виртуальной машины Azure.

Создание учетной записи SendGrid

Для использования услуг SendGrid вам сначала необходимо иметь учетную запись SendGrid. Перейдите на страницу Регистрация, и вы должны увидеть форму, как показано ниже. Введите свой адрес электронной почты и выберите пароль. Затем примите условия и нажмите кнопку Создать учетную запись.

Signing up for a free SendGrid account

На следующей странице вам нужно ввести свое имя и информацию о компании. Вы также должны выбрать соответствующие параметры, такие как ваша роль, количество отправляемых писем в месяц и количество сотрудников. Затем нажмите Начать.

Entering your account information

Когда вы впервые входите в систему SendGrid, вы можете получить сообщение об ошибке, говорящее: “У вас нет разрешения на доступ к SendGrid; обратитесь в службу поддержки.” Когда это происходит, откройте обращение в службу поддержки SendGrid. Они могут задать некоторые вопросы для подтверждения перед разблокировкой вашего доступа.

Вам будет предложено включить двухфакторную аутентификацию при первом входе в систему. Убедитесь, что следуете инструкциям точно.

Создание идентификатора отправителя SendGrid

После создания учетной записи SendGrid следующим шагом будет авторизация идентификатора отправителя. Есть два варианта: аутентификация отдельного отправителя (например, [email protected]) или аутентификация всего домена (например, domain.com).

В этом примере вы создадите идентификатор отправителя, который будет использоваться в качестве вашего адреса отправителя. Через SendGrid можно отправлять сообщения только с подтвержденного адреса отправителя. Следуйте инструкциям ниже, чтобы создать отдельный идентификатор отправителя.

  1. На странице Добро пожаловать нажмите кнопку Создать отдельного отправителя.
Creating a single sender

2. Затем, на всплывающей панели Создать отправителя, введите все необходимую информацию. Обязательные поля отмечены красной звездочкой для удобства. После ввода данных нажмите Создать.

Providing the sender details

Затем вы увидите новый отправительский адрес, перечисленный на странице Проверка одиночного отправителя. Как видно из приведенного ниже примера, адрес еще не подтвержден, что указано красным значком X в столбце ПОДТВЕРЖДЕНО.

Viewing the sender address verification status

3. Чтобы подтвердить отправителя, найдите электронное письмо, отправленное на адрес отправителя, похожее на скриншот ниже. Затем нажмите кнопку Подтвердить одиночного отправителя.

Verifying the Single Sender address

Адрес отправителя будет подтвержден. Вы должны увидеть подобную страницу, как показано ниже, подтверждающую, что проверка отправителя завершена.

Confirming that the sender address verification is complete

Создание ключа API SendGrid

После создания адреса одиночного отправителя интерфейс для создания ключей API становится доступным. Подумайте о ключе API SendGrid как о пароле. Без него ваш код не сможет аутентифицироваться с помощью службы ретрансляции SMTP SendGrid. Следуйте приведенным ниже шагам, чтобы создать новый ключ API.

  1. На левой панели меню нажмите Настройки > Ключи API. Затем нажмите кнопку Создать ключ API в правом верхнем углу страницы.
Creating a new SendGrid API key

2. Появляется всплывающее окно Создать ключ API. Введите имя создаваемого ключа API. Используйте понятное имя, например, “Azure Testing API Key”. Затем, для упрощения, выберите разрешение Полный доступ. Наконец, нажмите кнопку Создать и просмотреть.

Naming the API key and choosing permissions

3. Показывается новый ключ API. Теперь скопируйте и сохраните ключ, потому что он больше не будет показан вам. После копирования ключа нажмите Готово.

Saving the new SendGrid API key

Отправка электронного письма из Azure с использованием ретрансляции SMTP SendGrid.

Теперь у вас есть необходимые компоненты (аккаунт, отправитель и ключ) для использования SendGrid для отправки электронных писем Azure. Пришло время проверить, работает ли служба реле SMTP SendGrid. В этом разделе вы будете использовать PowerShell для отправки электронных писем с виртуальной машины Azure.

Перед запуском любого кода вам следует знать следующие требования.

  • Адрес сервера SMTP SendGrid – smtp.sendgrid.net.
  • Имя пользователя для аутентификации SMTP всегда apikey.
  • Пароль для использования – значение ключа API, созданного в SendGrid.
  • Не используйте порт 25. Вместо этого используйте порт 587.
  • Для отправки электронных писем можно использовать только проверенный адрес отправителя в SendGrid. В этом примере авторизованный отправитель – [email protected].

Ниже приведен скрипт для отправки электронного письма через реле SMTP SendGrid. Скопируйте код ниже и измените значения $sendGridApiKey, From, To и Body. Затем выполните код в вашей сессии PowerShell. Следуйте комментариям, чтобы понять, что делает каждая строка кода.

# Установите здесь свой API-ключ
$sendGridApiKey = 'SG...........P258'

$SendGridEmail = @{
	# Используйте свой проверенный адрес отправителя.
	From = '[email protected]'
	# Укажите адрес электронной почты получателя. Должен работать любой действительный адрес электронной почты.
	To = '[email protected]'
	# Обновите это поле с темой электронной почты, которую вы хотите использовать.
	Subject = 'This is a test message from Azure via SendGrid'
	# Обновите это поле с текстом электронного письма или сообщением, которое вы хотите отправить.
	Body = 'This is a test message from Azure via SendGrid'
	
	# НЕ ИЗМЕНЯЙТЕ НИЧЕГО НИЖЕ ЭТОЙ СТРОКИ
	SmtpServer = 'smtp.sendgrid.net'
	Port = 587
	UseSSL = $true
	Credential = New-Object PSCredential 'apikey', (ConvertTo-SecureString $sendGridApiKey -AsPlainText -Force)	
}

# Отправить электронное письмо
Send-MailMessage @SendGridEmail

В приведенном ниже примере показано, как выглядит выполнение указанного выше кода в PowerShell в режиме реального времени.

Sending an Email from Azure using SendGrid SMTP Relay

Чтобы подтвердить возможность доставки электронной почты, проверьте почтовый ящик получателя, чтобы найти тестовое сообщение, которое вы отправили. Результат будет аналогичен показанному ниже. Как видите, сообщение пришло с адреса отправителя через sendgrid.net.

Confirming the SMTP test message was delivered

Связано: Send-MailMessage: способ отправки электронной почты в PowerShell

Отправка электронной почты из Azure с использованием API SendGrid

Еще один способ использования SendGrid с Azure для отправки электронной почты – использование API Web SendGrid V3. Вместо взаимодействия с SendGrid по протоколу SMTP, с API общение осуществляется по протоколу HTTP. Запрос HTTP отправляется на конечную точку API SendGrid.

Ниже приведен пример скрипта PowerShell, который использует командлет Invoke-RestMethod для отправки электронной почты от Azure к SendGrid. Скопируйте код и измените значения переменных $sendGridApiKey, $fromAddress, $toAddress, $mailSubject и $mailMessage.

После обновления переменных выполните код в 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

После выполнения указанного выше кода PowerShell проверьте почтовый ящик получателя и подтвердите получение тестового сообщения. В приведенном ниже примере показано успешно доставленное тестовое сообщение от Azure через API SendGrid.

Confirming the API test message was delivered

Если вы хотите узнать больше о SendGrid Web API, посетите страницу V3 Mail Send API.

Использование Office 365 SMTP Auth

Другой вариант отправки электронной почты от Azure – использовать ретрансляцию SMTP Office 365. Это возможно, если в вашей организации уже есть подписка на Exchange Online. Как и при использовании SendGrid в качестве умного хоста SMTP, для ретрансляции SMTP Office 365 требуется аутентификация и использование только порта 587.

Перед использованием ретрансляции SMTP Office 365 вам необходимо знать следующие условия для ее работы.

  • Адрес отправителя должен быть действительным объектом получателя Exchange Online, таким как почтовый ящик или пользователь почты. Однако, если требуется сохранять уведомления о недоставке (NDR), используйте почтовый ящик.
  • Пользователь аутентификации должен иметь действительную лицензию Exchange Online. Только зарегистрированные пользователи Exchange Online имеют право использовать ретрансляцию SMTP Office 365.
  • Предположим, что пользователь аутентификации отличается от отправителя. В этом случае пользователю необходимо назначить разрешение Отправка от имени учетной записи отправителя.
  • Используемый метод аутентификации – базовая (устаревшая). Это означает, что если базовая аутентификация SMTP отключена в вашей организации или когда Microsoft окончательно откажется от базовой аутентификации, SMTP Auth больше не будет работать.
  • Адрес сервера ретрансляции SMTP – smtp.office365.com, и номер порта – 587.

Связано: Как отправить электронное письмо с помощью Office 365 Direct Send и PowerShell

Создание адреса отправителя в Office 365

В этом примере отправитель и пользователь аутентификации разные. Убедитесь, что сначала подключитесь к Exchange Online PowerShell. После подключения следуйте приведенным ниже шагам.

Создайте общий почтовый ящик с помощью следующей команды. Измените значения -Name и -PrimarySMTPAddress на свои корректные значения.

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

Общий почтовый ящик должен быть создан и вернуть результат, аналогичный приведенному ниже.

Creating a new shared mailbox as the sender

Затем назначьте разрешение Отправить от имени для пользователя аутентификации. В приведенном ниже примере пользователю назначено разрешение Отправить от имени для общего почтового ящика.

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

После выполнения вышеуказанной команды, вы должны получить результат, аналогичный приведенному ниже.

Assigning Send As permission

Отправка электронной почты из Azure с использованием ретрансляции SMTP Office 365

После создания адреса отправителя и назначения разрешения

Отправить от имени следующим шагом будет проверка доставки электронной почты с помощью PowerShell и ретрансляции SMTP Office 365. Код ниже выполняет аутентификацию с использованием [email protected]. Адрес [email protected] отображается в качестве отправителя. Убедитесь, что перед запуском кода вы назначили правильные значения.

# Укажите учетные данные SMTP
$username = '[email protected]'
$password = '*************'

# Укажите адрес электронной почты отправителя и получателя
$fromAddress = '[email protected]'
$toAddress = '[email protected]'

# Укажите тему письма и сообщение
$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'

# НЕ ИЗМЕНЯЙТЕ НИЧЕГО НИЖЕ ЭТОЙ СТРОКИ
$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)	
}

# Отправка электронной почты
Send-MailMessage @Office365RelayEmail

Использование учетных данных в скриптах в открытом виде не рекомендуется. Продакшн-скрипты должны использовать зашифровку учетных данных или управление секретами для защиты имен пользователей и паролей.

Теперь пришло время проверить почтовый ящик получателя. Подтвердите получение тестового сообщения.

Confirming the Office 365 SMTP relay test message was delivered

Использование Microsoft Graph API для отправки электронной почты Azure.

Вместо использования реле SMTP Office 365 более безопасным и рекомендуемым способом является использование Microsoft Graph API. С помощью Microsoft Graph API вы можете отправлять электронные письма из любого почтового ящика в вашей организации с помощью вызовов REST API.

Чтобы использовать Microsoft Graph API для отправки электронных писем, требуется зарегистрированное приложение Azure AD. Зарегистрированному приложению должно быть назначено разрешение API Mail.Send. В следующих разделах показано, как настроить Microsoft Graph API и использовать его для отправки электронных писем.

См. также: Использование Microsoft Graph API с PowerShell

Регистрация нового приложения в Azure Active Directory

В этом разделе вы зарегистрируете новое веб-приложение в активном каталоге Azure. Новое приложение будет использоваться в качестве идентификационного средства аутентификации для Microsoft Graph. Если вы еще не вошли в систему, выполните вход в Портал Azure.

  1. Перейдите в «Azure Active Directory —> Регистрация приложений». Затем нажмите кнопку Зарегистрировать новое приложение.
Creating a new app registration

2. На странице Регистрация приложения введите имя приложения.

3. Под Поддерживаемые типы учетных записей выберите Только учетные записи в этом организационном каталоге. Введите HTTP://localhost в качестве URI перенаправления. Наконец, нажмите кнопку Зарегистрировать.

Registering an application

4. Подождите завершения регистрации. Процесс занимает всего несколько секунд. Не забудьте записать полученный Идентификатор приложения (клиента) и Идентификатор каталога (арендатора). Вам понадобятся позже.

Saving the Application ID and Directory values

Создание секретного ключа клиента

Представьте себе идентификатор приложения, созданный в предыдущем разделе, как имя пользователя. И этому идентификатору приложения нужен пароль – который является секретным ключом.

Чтобы добавить новый секретный ключ приложения, выполните следующие шаги.

  1. Перейдите в раздел Сертификаты и секреты, затем нажмите Новый клиентский секрет.
  2. Введите описание для клиентского секрета, например, key1.
  3. Выберите срок действия секретного ключа и нажмите Добавить. В приведенном ниже примере секретный ключ истекает через 1 год.
Adding a new client secret key

Новый ключ будет отображаться в разделе Секреты клиента. Сохраните копию ключа, так как это единственное время, когда вы его увидите.

Viewing the client secret key value

Теперь, когда вы создали идентификатор и секрет приложения, осталось назначить необходимое разрешение для API Microsoft Graph. Без назначения разрешения приложение сможет аутентифицироваться, но не будет иметь полномочий для выполнения любых действий, например, для отправки электронной почты.

Чтобы начать назначение разрешения, выполните следующие шаги.

  1. Нажмите на Разрешения API в левом меню.

2. Затем, на странице Настроенные разрешения, нажмите кнопку Добавить разрешение.

Adding API permission

3. Во всплывающем окне Запрос разрешений API нажмите, чтобы выбрать API Microsoft Graph.

Selecting Microsoft Graph API

4. При запросе выбора типа необходимого разрешения для приложения, щелкните на Разрешения приложения.

5. В поле поиска введите Mail.Send, чтобы найти его. В результатах выберите разрешение Mail.Send. Наконец, нажмите на Добавить разрешения.

Assigning mail.send permission

6. Вы увидите, что статус разрешения “Не предоставлено для <имя организации>”. В этой точке вы или глобальный администратор должны предоставить согласие на использование приложения. Чтобы предоставить разрешение, нажмите кнопку Предоставить согласие администратора для <организации>.

Granting Admin consent

Затем статус разрешения API изменится на “Предоставлено для <имя организации>”.

Confirming the API permission status

Получение маркера доступа

Запросы, отправленные в API Microsoft Graph, требуют маркера доступа. На этом этапе у вас уже есть идентификатор приложения, секретный ключ и идентификатор арендатора. Эти три элемента информации необходимы для получения маркера доступа.

Приведенный ниже сценарий PowerShell отправляет запрос на получение маркера доступа в конечную точку API Microsoft Graph. Сначала вам необходимо обновить значения $client_id, $client_secret и $tenant_id на свои правильные значения. Затем скопируйте и вставьте код в PowerShell для запроса маркера доступа.

# замените на идентификатор вашего приложения
$client_id = 'APPLICATION ID'
# замените на секретный ключ
$client_secret = 'SECRET KEY'
# замените на идентификатор арендатора
$tenant_id = 'TENANT ID'

# НИЧЕГО НЕ ИЗМЕНЯЙТЕ НИЖЕ ЭТОЙ СТРОКИ
$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
        }
    }
# Получите токен доступа
$token = (Invoke-RestMethod @request).access_token
# просмотр значения токена
$token

Демонстрация ниже показывает работу указанного выше сценария PowerShell. Обратите внимание, что запрошенный токен доступа сохраняется в переменной $token.

Requesting access token

Токены доступа действительны только в течение одного (1) часа с момента получения. Вам нужно будет запросить новый токен доступа после истечения срока действия предыдущего.

Отправка электронной почты из Azure с использованием Microsoft Graph API

Теперь вы готовы использовать Microsoft Graph API с Azure для 

# Укажите адрес электронной почты отправителя и получателя
$fromAddress = 'SENDER ADDRESS HERE'
$toAddress = 'RECIPIENT ADDRESS HERE'

# Укажите тему письма и сообщение
$mailSubject = 'This is a test message from Azure via Microsoft Graph API'
$mailMessage = 'This is a test message from Azure via Microsoft Graph API'

# НЕ ИЗМЕНЯЙТЕ НИЧЕГО НИЖЕ ЭТОЙ СТРОКИ
# Сформируйте запрос к 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
}

# Отправьте сообщение
Invoke-RestMethod @params -Verbose


Source:
https://adamtheautomator.com/azure-send-email/