Как отправлять электронную почту с помощью SendGrid и AzureHow to Send Email Using SendGrid with Azure

ОбзорOverview

В этом руководстве показано, как выполнять типовые задачи программирования для службы электронной почты SendGrid в Azure.This guide demonstrates how to perform common programming tasks with the SendGrid email service on Azure. Примеры написаны на языке C# и поддерживают .NET Standard 1.3.The samples are written in C# and supports .NET Standard 1.3. Здесь описываются сценарии создания электронного сообщения, его отправки, добавления вложений и включения различных параметров электронной почты и отслеживания.The scenarios covered include constructing email, sending email, adding attachments, and enabling various mail and tracking settings. Дополнительные сведения о SendGrid и отправке электронной почты см. в разделе Дальнейшие действия.For more information on SendGrid and sending email, see the Next steps section.

Что такое служба электронной почты SendGrid?What is the SendGrid Email Service?

SendGrid — это облачная служба электронной почты, которая обеспечивает надежную [доставку транзакционных писем], предоставляет возможности масштабирования и аналитики в реальном времени, а также предоставляет гибкие интерфейсы API для пользовательской интеграции.SendGrid is a cloud-based email service that provides reliable transactional email delivery, scalability, and real-time analytics along with flexible APIs that make custom integration easy. Наиболее распространенные варианты использования SendGrid:Common SendGrid use cases include:

  • Автоматическая отправка клиентам квитанций или сообщений о подтверждении покупки.Automatically sending receipts or purchase confirmations to customers.
  • Администрирование списков рассылки для ежемесячной отправки клиентам рекламных листовок и рекламы.Administering distribution lists for sending customers monthly fliers and promotions.
  • Сбор метрик в реальном времени по таким параметрам, как заблокированная электронная почта и взаимодействие с клиентами.Collecting real-time metrics for things like blocked email and customer engagement.
  • Пересылка запросов клиентов.Forwarding customer inquiries.
  • Обработка входящих сообщений электронной почты.Processing incoming emails.

Для получения дополнительной https://sendgrid.com информации посетите или библиотеку S' S' GitHub репо.For more information, visit https://sendgrid.com or SendGrid's C# library GitHub repo.

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

Клиенты Azure могут разблокировать 25 000 бесплатных сообщений электронной почты каждый месяц.Azure customers can unlock 25,000 free emails each month. Эти 25000 бесплатных ежемесячных писем даст вам доступ к расширенной отчетности и аналитики и всех AA (Web, SMTP, Event, Parse и многое другое).These 25,000 free monthly emails will give you access to advanced reporting and analytics and all APIs (Web, SMTP, Event, Parse, and more). Сведения о дополнительных службах, предоставляемых SendGrid, см. на странице решений SendGrid.For information about additional services provided by SendGrid, visit the SendGrid Solutions page.

Регистрация для получения учетной записи SendGridTo sign up for a SendGrid account

  1. Войдите на портал Azure.Sign in to the Azure portal.

  2. В меню портала Azure или на главной странице выберите «Создайте ресурс».In the Azure portal menu or the home page, select Create a resource.

    command-bar-new

  3. Поиск и выбор SendGrid.Search for and select SendGrid.

    sendgrid-store

  4. Заполните форму регистрации и щелкните Создать.Complete the signup form and select Create.

    sendgrid-create

  5. Введите имя, идентифицирующее службу SendGrid, в параметрах настройки Azure.Enter a Name to identify your SendGrid service in your Azure settings. Имена должны иметь длину в диапазоне от 1 до 100 знаков и содержать только алфавитно-цифровые символы, дефисы, точки и подчеркивания.Names must be between 1 and 100 characters in length and contain only alphanumeric characters, dashes, dots, and underscores. Имя должно быть уникальным в списке элементов Магазина Azure, на которые вы подписались.The name must be unique in your list of subscribed Azure Store Items.

  6. Введите и подтвердите пароль.Enter and confirm your Password.

  7. Выберите подписку.Choose your Subscription.

  8. Создайте новую группу ресурсов или выберите существующую.Create a new Resource group or use an existing one.

  9. В разделе Ценовая категория выберите план SendGrid для регистрации.In the Pricing tier section select the SendGrid plan you want to sign up for.

    sendgrid-pricing

  10. Введите промокод (при наличии).Enter a Promotion Code if you have one.

  11. Введите контактные данные.Enter your Contact Information.

  12. Просмотрите и примите юридические условия.Review and accept the Legal terms.

  13. После подтверждения покупки вы увидите всплывающее окно Deployment Succeeded и увидите свою учетную запись в списке.After confirming your purchase you will see a Deployment Succeeded pop-up and you will see your account listed.

    all-resources

    После того, как вы завершите покупку и нажмете кнопку Управление, чтобы запустить процесс проверки по электронной почте, вы получите электронное сообщение с предложением подтвердить учетную запись SendGrid.After you have completed your purchase and clicked the Manage button to initiate the email verification process, you will receive an email from SendGrid asking you to verify your account. Если вы не получили это письмо или у вас возникли проблемы с проверкой вашей учетной записи, пожалуйста, ознакомьтесь с нашими часто задаваемыми вопросами.If you do not receive this email, or have problems verifying your account, please see our FAQ.

    управление

    Пока вы не подтвердили свою учетную запись, вы можете отправлять до 100 электронных сообщений в день.You can only send up to 100 emails/day until you have verified your account.

    Для изменения плана подписки или просмотра параметров контактов SendGrid выберите имя службы SendGrid, чтобы открыть панель мониторинга SendGrid Marketplace.To modify your subscription plan or see the SendGrid contact settings, click the name of your SendGrid service to open the SendGrid Marketplace dashboard.

    Параметры

    Чтобы отправить электронное сообщение с помощью SendGrid, необходимо указать ключ API.To send an email using SendGrid, you must supply your API Key.

Как найти ключ API SendGridTo find your SendGrid API Key

  1. Нажмите кнопку Управление.Click Manage.

    управление

  2. На панели мониторинга SendGrid в меню слева выберите Параметры > Ключи API.In your SendGrid dashboard, select Settings and then API Keys in the menu on the left.

    api-keys

  3. Щелкните Создать ключ API.Click the Create API Key.

    general-api-key

  4. Как минимум укажите имя ключа и предоставьте полный доступ для отправки почты. Затем щелкните Сохранить.At a minimum, provide the Name of this key and provide full access to Mail Send and select Save.

    access

  5. На этом этапе API будет отображен один раз.Your API will be displayed at this point one time. Обязательно сохраните его в надежном месте.Please be sure to store it safely.

Поиск учетных данных SendGridTo find your SendGrid credentials

  1. Щелкните значок ключа, чтобы найти свое имя пользователя.Click the key icon to find your Username.

    ключ

  2. Используется пароль, который вы выбрали при установке.The password is the one you chose at setup. Можно выбрать Смена пароля или Сброс пароля, чтобы внести изменения.You can select Change password or Reset password to make any changes.

Чтобы настроить параметры доставки электронной почты, нажмите кнопку Управление.To manage your email deliverability settings, click the Manage button. Откроется панель мониторинга SendGrid.This will redirect to your SendGrid dashboard.

управление

Дополнительные сведения об отправке по электронной почте посредством SendGrid см. в обзоре API электронной почты.For more information on sending email through SendGrid, visit the Email API Overview.

Справочник по библиотеке классов SendGrid .NETReference the SendGrid .NET Class Library

Пакет SendGrid NuGet — это самый простой способ получить интерфейс API службы SendGrid и настроить свое приложение с учетом всех зависимостей.The SendGrid NuGet package is the easiest way to get the SendGrid API and to configure your application with all dependencies. Пакет NuGet — это расширение Visual Studio, включенное в Microsoft Visual Studio 2015 в более поздние версии, которое упрощает установку и обновление библиотек и инструментов.NuGet is a Visual Studio extension included with Microsoft Visual Studio 2015 and above that makes it easy to install and update libraries and tools.

Примечание

Чтобы установить NuGet, если вы работаете версия Visual Studio раньше, чем Visual Studio 2015, посетите https://www.nuget.orgкнопку Install NuGet.To install NuGet if you are running a version of Visual Studio earlier than Visual Studio 2015, visit https://www.nuget.org, and click the Install NuGet button.

Для установки пакета SendGrid NuGet в приложении выполните следующие действия:To install the SendGrid NuGet package in your application, do the following:

  1. Щелкните Новый проект и выберите Шаблон.Click on New Project and select a Template.

    Создание нового проекта

  2. В обозревателе решений щелкните правой кнопкой мыши Ссылки, а затем выберите Управление пакетами NuGet.In Solution Explorer, right-click References, then click Manage NuGet Packages.

    Пакет SendGrid NuGet

  3. Выполните поиск SendGrid и выберите элемент SendGrid в списке результатов.Search for SendGrid and select the SendGrid item in the results list.

  4. Выберите последнюю стабильную версию пакета NuGet из раскрывающегося списка версий, чтобы иметь возможность работать с объектной моделью и интерфейсами API, описанными в этой статье.Select the latest stable version of the Nuget package from the version dropdown to be able to work with the object model and APIs demonstrated in this article.

    Пакет SendGrid

  5. Нажмите кнопку Установить , чтобы выполнить установку, а затем закройте диалоговое окно.Click Install to complete the installation, and then close this dialog.

Библиотека классов SendGrid .NET называется SendGrid.SendGrid's .NET class library is called SendGrid. Она содержит такие пространства имен:It contains the following namespaces:

  • SendGrid для общения с API SendGrid.SendGrid for communicating with SendGrid's API.
  • SendGrid.Helpers.Mail для вспомогательных методов, используемых для создания объектов SendGridMessage, определяющих способ отправки электронных сообщений.SendGrid.Helpers.Mail for helper methods to easily create SendGridMessage objects that specify how to send emails.

Добавьте следующие объявления пространств имен кода в начало любого файла C#, в котором вы собираетесь получать доступ к хранилищу службы электронной почты SendGrid программным способом.Add the following code namespace declarations to the top of any C# file in which you want to programmatically access the SendGrid email service.

using SendGrid;
using SendGrid.Helpers.Mail;

Практическое руководство. Создание сообщения эл. почтыHow to: Create an Email

Для создания сообщения электронной почты используется объект SendGridMessage .Use the SendGridMessage object to create an email message. После создания объекта сообщения можно задать свойства и методы, включая отправителя и получателя электронной почты, тему и текст сообщения.Once the message object is created, you can set properties and methods, including the email sender, the email recipient, and the subject and body of the email.

В следующем примере показано, как создать полностью заполненный объект электронной почты.The following example demonstrates how to create a fully populated email object:

var msg = new SendGridMessage();

msg.SetFrom(new EmailAddress("dx@example.com", "SendGrid DX Team"));

var recipients = new List<EmailAddress>
{
    new EmailAddress("jeff@example.com", "Jeff Smith"),
    new EmailAddress("anna@example.com", "Anna Lidman"),
    new EmailAddress("peter@example.com", "Peter Saddow")
};
msg.AddTos(recipients);

msg.SetSubject("Testing the SendGrid C# Library");

msg.AddContent(MimeType.Text, "Hello World plain text!");
msg.AddContent(MimeType.Html, "<p>Hello World!</p>");

Дополнительные сведения о всех свойствах и методах, поддерживаемых типом SendGrid, см. в разделе sendgrid-csharp на портале GitHub.For more information on all properties and methods supported by the SendGrid type, see sendgrid-csharp on GitHub.

Практическое руководство. Отправка сообщения эл. почтыHow to: Send an Email

После создания сообщения электронной почты его можно отправить с помощью API SendGrid.After creating an email message, you can send it using SendGrid's API. Можно также воспользоваться встроенной библиотекой .NET.Alternatively, you may use .NET's built in library.

Чтобы отправить электронное сообщение, необходимо указать ключ API SendGrid.Sending email requires that you supply your SendGrid API Key. Если требуются сведения о том, как настроить ключи API SendGrid, ознакомьтесь с нашей документацией по ключам API SendGrid.If you need details about how to configure API Keys, please visit SendGrid's API Keys documentation.

Вы можете хранить эти учетные данные через портал Azure, нажав на настройки приложения и добавив пары ключей/значений в настройках приложения.You may store these credentials via your Azure portal by clicking Application settings and adding the key/value pairs under App settings.

Параметры приложения Azure

После этого обращаться к ним можно следующим образом.Then, you may access them as follows:

var apiKey = System.Environment.GetEnvironmentVariable("SENDGRID_APIKEY");
var client = new SendGridClient(apiKey);

В следующих примерах показано, как отправить сообщение электронной почты с помощью веб-интерфейса API SendGrid с консольным приложением.The following examples show how to send an email message using the SendGrid Web API with a console application.

using System;
using System.Threading.Tasks;
using SendGrid;
using SendGrid.Helpers.Mail;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = System.Environment.GetEnvironmentVariable("SENDGRID_APIKEY");
            var client = new SendGridClient(apiKey);
            var msg = new SendGridMessage()
            {
                From = new EmailAddress("test@example.com", "DX Team"),
                Subject = "Hello World from the SendGrid CSharp SDK!",
                PlainTextContent = "Hello, Email!",
                HtmlContent = "<strong>Hello, Email!</strong>"
            };
            msg.AddTo(new EmailAddress("test@example.com", "Test User"));
            var response = await client.SendEmailAsync(msg);
        }
    }
}

Как отправить электронное сообщение из API .NET Core ASP с помощью класса MailHelperHow to: Send email from ASP .NET Core API using MailHelper class

Пример ниже можно использовать для отправки одного сообщения нескольким лицам из API .NET Core ASP с помощью класса MailHelper пространства имен SendGrid.Helpers.Mail.The below example can be used to send a single email to multiple persons from the ASP .NET Core API using the MailHelper class of SendGrid.Helpers.Mail namespace. В этом примере используется .NET Core 1.0 ASP.For this example we are using ASP .NET Core 1.0.

В этом примере ключ API был сохранен в файл appsettings.json, который можно переопределить с портала Azure, как показано в примерах выше.In this example, the API key has been stored in the appsettings.json file which can be overridden from the Azure portal as shown in the above examples.

Содержимое файла appsettings.json должно выглядеть следующим образом:The contents of appsettings.json file should look similar to:

{
   "Logging": {
   "IncludeScopes": false,
   "LogLevel": {
   "Default": "Debug",
   "System": "Information",
   "Microsoft": "Information"
     }
   },
 "SENDGRID_API_KEY": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Сначала необходимо добавить код ниже в файл Startup.cs проекта API .NET Core.First, we need to add the below code in the Startup.cs file of the .NET Core API project. Это необходимо для получения доступа к разделу SENDGRID_API_KEY из файла appsettings.json с помощью внедрения зависимости в контроллере API.This is required so that we can access the SENDGRID_API_KEY from the appsettings.json file by using dependency injection in the API controller. Интерфейс IConfiguration можно внедрить в конструктор контроллера после его добавления в метод ConfigureServices ниже.The IConfiguration interface can be injected at the constructor of the controller after adding it in the ConfigureServices method below. После добавления нужного кода содержимое файла Startup.cs будет выглядеть примерно следующим образом:The content of Startup.cs file looks like the following after adding the required code:

    public IConfigurationRoot Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        // Add mvc here
        services.AddMvc();
        services.AddSingleton<IConfiguration>(Configuration);
    }

После внедрения интерфейса IConfiguration в контроллер метод CreateSingleEmailToMultipleRecipients класса MailHelper можно использовать для отправки одного электронного сообщения нескольким получателям.At the controller, after injecting the IConfiguration interface, we can use the CreateSingleEmailToMultipleRecipients method of the MailHelper class to send a single email to multiple recipients. Этот метод принимает один дополнительный логический параметр с именем showAllRecipients.The method accepts one additional boolean parameter named showAllRecipients. Его можно использовать для управления возможностью получателей видеть адреса электронной почты друг друга в заголовке сообщения электронной почты в разделе "Кому".This parameter can be used to control whether email recipients will be able to see each others email address in the To section of email header. Пример кода для контроллера должен выглядеть примерно как показано ниже:The sample code for controller should be like below

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using SendGrid;
using SendGrid.Helpers.Mail;
using Microsoft.Extensions.Configuration;

namespace SendgridMailApp.Controllers
{
    [Route("api/[controller]")]
    public class NotificationController : Controller
    {
       private readonly IConfiguration _configuration;

       public NotificationController(IConfiguration configuration)
       {
         _configuration = configuration;
       }      
    
       [Route("SendNotification")]
       public async Task PostMessage()
       {
          var apiKey = _configuration.GetSection("SENDGRID_API_KEY").Value;
          var client = new SendGridClient(apiKey);
          var from = new EmailAddress("test1@example.com", "Example User 1");
          List<EmailAddress> tos = new List<EmailAddress>
          {
              new EmailAddress("test2@example.com", "Example User 2"),
              new EmailAddress("test3@example.com", "Example User 3"),
              new EmailAddress("test4@example.com","Example User 4")
          };
        
          var subject = "Hello world email from Sendgrid ";
          var htmlContent = "<strong>Hello world with HTML content</strong>";
          var displayRecipients = false; // set this to true if you want recipients to see each others mail id 
          var msg = MailHelper.CreateSingleEmailToMultipleRecipients(from, tos, subject, "", htmlContent, false);
          var response = await client.SendEmailAsync(msg);
      }
   }
}

Практическое руководство. Добавление вложенияHow to: Add an attachment

Чтобы добавить вложение в сообщение, вызовите метод AddAttachment и по крайней мере укажите имя файла и содержимое в кодировке Base64 для вложения.Attachments can be added to a message by calling the AddAttachment method and minimally specifying the file name and Base64 encoded content you want to attach. Можно добавить несколько вложений, вызывая этот метод для каждого вкладываемого файла. Можно также использовать метод AddAttachments.You can include multiple attachments by calling this method once for each file you wish to attach or by using the AddAttachments method. На приведенном ниже примере продемонстрировано добавление вложения в сообщение.The following example demonstrates adding an attachment to a message:

var banner2 = new Attachment()
{
    Content = Convert.ToBase64String(raw_content),
    Type = "image/png",
    Filename = "banner2.png",
    Disposition = "inline",
    ContentId = "Banner 2"
};
msg.AddAttachment(banner2);

Практическое руководство. Использование параметров почты для добавления нижних колонтитулов, отслеживания и аналитикиHow to: Use mail settings to enable footers, tracking, and analytics

SendGrid обеспечивает дополнительные функции электронной почты благодаря использованию параметров почты и отслеживания.SendGrid provides additional email functionality through the use of mail settings and tracking settings. Эти параметры можно добавлять в сообщения для включения определенных функций, например отслеживания щелчков, аналитики Google, отслеживания подписок и т. п.These settings can be added to an email message to enable specific functionality such as click tracking, Google analytics, subscription tracking, and so on. Полный список приложений приведен в документации по параметрам.For a full list of apps, see the Settings Documentation.

Приложения можно использовать в электронных сообщениях SendGrid с помощью методов, реализованных в рамках класса SendGridMessage.Apps can be applied to SendGrid email messages using methods implemented as part of the SendGridMessage class. В следующих примерах показаны фильтры нижних колонтитулов и отслеживания щелчков:The following examples demonstrate the footer and click tracking filters:

В следующих примерах показаны фильтры нижних колонтитулов и отслеживания щелчков:The following examples demonstrate the footer and click tracking filters:

msg.SetFooterSetting(
                     true,
                     "Some Footer HTML",
                     "<strong>Some Footer Text</strong>");

Отслеживание щелчковClick tracking

msg.SetClickTracking(true);

Практическое руководство. Использование дополнительных служб SendGridHow to: Use Additional SendGrid Services

SendGrid предоставляет несколько интерфейсов API и объектов webhook, с помощью которых в своем приложении Azure можно использовать дополнительные функции.SendGrid offers several APIs and webhooks that you can use to leverage additional functionality within your Azure application. Дополнительные сведения см. в справочнике по API SendGrid.For more details, see the SendGrid API Reference.

Дальнейшие действияNext steps

Вы получили основные сведения о службе доставки электронной почты SendGrid. Дополнительные сведения вы найдете по следующим ссылкам.Now that you've learned the basics of the SendGrid Email service, follow these links to learn more.