Отправка email-сообщения с явным указанием учетных данных

Общие сведения

В Сreatio вы можете отправлять email-сообщения не только пользовательскими средствами, но и средствами разработки. Это реализуется следующими способами:

• С существующей учетной записи.
• С явным указанием учетных данных.

В этой статье рассмотрен способ отправки email-сообщения с явным указанием учетных данных. Как отправить письмо с существующей учетной записи, читайте в статье "Отправка email-сообщения с существующей учетной записи".

Отправка email-сообщения с явным указанием учетных данных реализована с помощью бизнес-процесса. Для настройки бизнес-процесса используются элементы [Автогенерируемая страница] ([Auto-generated page]) и [Задание-сценарий] ([Script task]).

Подготовка и отправка email-сообщения

Для отправки email-сообщения с явным указанием учетных необходимо выполнить следующие действия:

1. Создать бизнес-процесс, который должен включать обязательные элементы [Автогенерируемая страница] и [Задание-сценарий].
2. Создать экземпляр класса EmailClientFactory.
3. Создать экземпляр класса EmailSender.
4. Создать конфиг подключения к почтовому ящику.
5. Создать конфиг отправляемого email-сообщения.
6. Добавить вложение (не обязательно).
7. Запустить бизнес-процесс для выполнения отправки.

Создание экземпляра класса EmailClientFactory

Для создания экземпляра класса EmailClientFactory необходимо наличие пользовательского подключения UserConnection.

var emailClientFactory = ClassFactory.Get<IEmailClientFactory>(
       new ConstructorArgument("userConnection", UserConnection));

Создание экземпляра класса EmailSender

Для создания экземпляра класса EmailSender необходимо передать в конструктор созданный экземпляр EmailClientFactory и пользовательское подключение UserConnection.

var emailSender = ClassFactory.Get<IEmailSender>(
     new ConstructorArgument("emailClientFactory", emailClientFactory),
     new ConstructorArgument("userConnection", UserConnection));

Создание конфига подключения к почтовому ящику

Для создания конфига подключения к почтовому ящику используется класс EmailContract.DTO.Credentials. Чтобы создать конфиг, заполните следующие параметры:

var credentialConfig = new EmailContract.DTO.Credentials {
    // Имя или IP-адрес сервера исходящей почты.
    ServiceUrl = "mail service host",
    // Может быть пустым для некоторых протоколов.
    Port = "Port",
    // Использовать протокол SSL для шифрования подключения.
    UseSsl = false,
    // Имя пользователя почтового ящика.
    UserName = "EmailUserName",
    // Пароль пользователя почтового ящика.
    Password = "UserPassword",
    // Тип почтового сервера (Exchange либо Imap/Smtp).
    ServerTypeId = EmailDomain.IntegrationConsts.ExchangeMailServerTypeId ||
             EmailDomain.IntegrationConsts.ImapMailServerTypeId,
    // Почтовый ящик отправителя.
    SenderEmailAddress = "sender@test.com"
};

Создание конфига отправляемого email-сообщения

Для создания конфига отправляемого email-сообщения необходимо использовать класс EmailContract.DTO.Email. Для формирования валидного email-сообщения заполните следующие параметры:

var message = new EmailContract.DTO.Email {
    // Email-адрес отправителя.
    Sender = "Sender@email.com",
    // Email-адреса получателей.
    Recepients = List<string>{ "first@recepient.co", "second@recepient.co"},
    // Тема письма.
    Subject = "Message subject",
    // Тело письма.
    Body = "Body",
    // Приоритет, значения из перечисления EmailContract.EmailImportance.
    Importance = EmailContract.EmailImportance.High
};

Добавление вложения (не обязательно)

В email-сообщение можно добавить вложение. Для этого необходимо заполнить поле [Attachments]. Вложения представляют собой список экземпляров EmailContract.DTO.Attachment.

// Создание вложения.
var attachment = new EmailContract.DTO.Attachment {
    Name = "FileName",
    Id = "844F0837-EAA0-4F40-B965-71F5DB9EAE6E"
};
// Установка данных для вложения.
attachment.SetData(byteData);
// Добавление вложения в письмо.
message.Attachments.Add(attachment);

Отправка email-сообщения

Для отправки письма необходимо использовать метод Send класса EmailSender c переданными аргументами email-сообщения и конфига подключения.

// Отправка сформированного email-сообщения с параметрами подключения к почтовому
// ящику отправителя. Для игнорирования прав доступа при отправке 
// требуется присвоить параметру ignoreRights значение true.
emailSender.Send(message, credentialConfig, ignoreRights);

Описание примера

Создайте бизнес-процесс в ходе которого будет открываться страница, содержащая параметры email-сообщения для заполнения и дальнейшей отправки email-сообщения с явным указанием учетных данных.

Исходный код

Пакет с реализацией примера можно скачать по ссылке.

Алгоритм реализации примера

1. Создайте бизнес-процесс

В разделе [Конфигурация] ([Configuration]) выполните действие [Добавить] —> [Бизнес-процесс] ([Add] —> [Business process]) (рис. 1).

Рис. 1. — Действие [Добавить] —> [Бизнес-процесс]

В открывшемся дизайнере процессов установите следующие значения на панели настройки свойств процесса (рис. 2):

• [Заголовок] ([Title]) — "Sending emails using the explicit account credentials".
• [Код] ([Code]) — "UsrSendEmailWithCredentialsProcess".

Рис. 2. — Свойства бизнес-процесса

2. Добавьте элемент [Автогенерируемая страница]

С помощью элемента [Автогенерируемая страница] ([Auto-generated page]) в ходе выполнения процесса можно открыть произвольную страницу, которая создана пользователем системы. Для этого элемента добавьте подпись [Filling parameters] и установите следующие свойства (рис. 3):

• [Название страницы] ([Page title]) — "Fill parameters for sending Email".
• [Кому отобразить страницу?] ([To whom should the page be shown?]) — выберите "Formula" и установите [#System variable.Current user contact#].

Рис. 3. — Свойства автогенерируемой страницы

3. Добавьте кнопку на страницу

Для добавления кнопки [Continue] на страницу, в блоке [Кнопки] ([Buttons]) нажмите и введите следующие параметры (рис. 4):

• [Название] ([Caption]) — "Continue".
• [Код] ([Code]) — "ContinueButton".
• [Стиль] ([Style]) — выберите "Green".
• Установите признак [Активная] ([Active]).
• Установите признак [Выполняет проверку значений] ([Performs value validation]).

Рис. 4. — Добавление кнопки на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

4. Добавьте элементы на страницу

Для добавления на страницу элемента, который будет содержать почтовый ящик отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 5):

• [Заголовок] ([Title]) — "Sender Mailbox".
• [Код] ([Code]) — "SenderMailbox".
• Установите признак [Обязательное] ([Required]).

Рис. 5. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать имя отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 6):

• [Заголовок] ([Title]) — "User Name".
• [Код] ([Code]) — "UserName".
• Установите признак [Обязательное] ([Required]).

Рис. 6. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать пароль к почтовому ящику отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 7):

• [Заголовок] ([Title]) — "Password".
• [Код] ([Code]) — "Password".
• Установите признак [Обязательное] ([Required]).

Рис. 7. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать адрес почтового сервера отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 8):

• [Заголовок] ([Title]) — "Service Url".
• [Код] ([Code]) — "ServiceUrl".
• Установите признак [Обязательное] ([Required]).

Рис. 8. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать номер порта почтового провайдера отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Целое число] ([Integer]) и введите следующие параметры (рис. 9):

• [Заголовок] ([Title]) — "Port".
• [Код] ([Code]) — "Port".

Рис. 9. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать криптографический протокол для обеспечения безопасной связи, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Логическое] ([Boolean]) и введите следующие параметры (рис. 10):

• [Заголовок] ([Title]) — "Use Ssl".
• [Код] ([Code]) — "UseSsl".

Рис. 10. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать почтовый ящик получателя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 11):

• [Заголовок] ([Title]) — "Recipient (many recipients separated by semicolon ";")".
• [Код] ([Code]) — "Recipient".
• Установите признак [Обязательное] ([Required]).

Рис. 11. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать тему email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 12):

• [Заголовок] ([Title]) — "Subject".
• [Код] ([Code]) — "Subject".
• Установите признак [Обязательное] ([Required]).

Рис. 12. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать тело email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Строковое поле] ([Text field]) и введите следующие параметры (рис. 13):

• [Заголовок] ([Title]) — "Body".
• [Код] ([Code]) — "Body".
• Установите признак [Обязательное] ([Required]).

Рис. 13. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

Для добавления на страницу элемента, который будет содержать тип почтового провайдера отправителя email-сообщения, в блоке [Параметры страницы] ([Page Items]) нажмите , выберите тип [Справочник] ([Selection field]) и введите следующие параметры (рис. 14):

• [Заголовок] ([Title]) — "Type of mail server".
• [Код] ([Code]) — "ServerTypeId".
• Установите признак [Обязательное] ([Required]).
• [Источник данных] ([Data source]) — выберите "Mail service provider type".
• [Представление] ([View]) — выберите "Drop down list".

Рис. 14. — Добавление элемента на автогенерируемую страницу

Нажмите [Сохранить] ([Save]).

5. Добавьте элемент [Задание-сценарий]

Свойству [Заголовок] ([Title]) элемента [Задание-сценарий] ([Script task]) присвойте значение "Send Email". Элемент должен выполнять следующий программный код:

// Создание экземпляра EmailClientFactory.
var emailClientFactory = ClassFactory.Get<EmailClientFactory>(new ConstructorArgument("userConnection", UserConnection));
// Установка параметров подключения к почтовому сервису.
var credentialConfig = new EmailContract.DTO.Credentials {
    ServiceUrl = Get<string>("ServiceUrl"),
    Port = Get<int>("Port"),
    UseSsl = Get<bool>("UseSsl"),
    UserName = Get<string>("UserName"),
    Password = Get<string>("Password"),
    ServerTypeId = Get<Guid>("ServerTypeId"),
    SenderEmailAddress = Get<string>("SenderMailbox")
};
// Создание экземпляра IEmailSender.
var emailSender = ClassFactory.Get<IEmailSender>(new ConstructorArgument("emailClientFactory", emailClientFactory),
    new ConstructorArgument("userConnection", UserConnection));
// Установка параметров отправляемого сообщения.
var message = new EmailContract.DTO.Email {
    Sender = credentialConfig.SenderEmailAddress,
    Recepients = Get<string>("Recipient").Split(';').ToList<string>(),
    Subject = Get<string>("Subject"),
    Body = Get<string>("Body"),
    Importance = EmailContract.EmailImportance.Normal,
    // Если тело письма было сформировано в формате HTML.
    IsHtmlBody = true,
    // Дополнительно можно указать список получателей в копии, в т.ч. скрытых
    // CopyRecepients = new List<string> { "user@mail.service" },
    // BlindCopyRecepients = new List<string> { "user@mail.service" }
};
// Создание вложения.
var attachment = new EmailContract.DTO.Attachment {
    // Идентификатор вложения.
    Id = Guid.NewGuid().ToString(),
    // Название файла.
    Name = "test.txt",
};
// Данные (используется тестовое значение данных в виде текста).
byte[] data = Encoding.ASCII.GetBytes("some test text");
// Добавление данных во вложение.
attachment.SetData(data);
// Добавление вложения в сообщение.
message.Attachments.Add(attachment);
// Отправка email-сообщения.
emailSender.Send(message, credentialConfig);                
return true;

6. Добавьте параметры

Для добавления параметра бизнес-процесса, который будет содержать адрес почтового сервера отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Текст] ([Add parameters] —> [Text]) и установите следующие свойства параметра (рис. 15):

• [Заголовок] ([Title]) — "Service Url".
• [Код] ([Code]) — "ServiceUrl".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Service Url".

Рис. 15. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать номер порта почтового провайдера отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Целое число] ([Add parameters] —> [Integer]) и установите следующие свойства параметра (рис. 16):

• [Заголовок] ([Title]) — "Port".
• [Код] ([Code]) — "Port".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Port".

Рис. 16. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать криптографический протокол для обеспечения безопасной связи, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Логическое] ([Add parameters] —> [Boolean]) и установите следующие свойства параметра (рис. 17):

• [Заголовок] ([Title]) — "Use Ssl".
• [Код] ([Code]) — "Use Ssl".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Use Ssl".

Рис. 17. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать имя отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Текст] ([Add parameters] —> [Text]) и установите следующие свойства параметра (рис. 18):

• [Заголовок] ([Title]) — "User Name".
• [Код] ([Code]) — "UserName".
• [Тип данных] ([Data type]) — выберите "Text (250 characters)".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "User Name".

Рис. 18. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать пароль к почтовому ящику отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Текст] ([Add parameters] —> [Text]) и установите следующие свойства параметра (рис. 19):

• [Заголовок] ([Title]) — "Password".
• [Код] ([Code]) — "Password".
• [Тип данных] ([Data type]) — выберите "Text (250 characters)".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Password".

Рис. 19. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать почтовый ящик получателя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Текст] ([Add parameters] —> [Text]) и установите следующие свойства параметра (рис. 20):

• [Заголовок] ([Title]) — "Recipient".
• [Код] ([Code]) — "Recipient".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Recipient (many recipients separated by semicolon ";")".

Рис. 20. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать тип почтового провайдера отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Другое] —> [Уникальный идентификатор] ([Add parameters] —> [Other] —> [Unique identifier]) и установите следующие свойства параметра (рис. 21):

• [Заголовок] ([Title]) — "Type of mail server".
• [Код] ([Code]) — "ServerTypeId".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Type of mail server".

Рис. 21. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

Для добавления параметра бизнес-процесса, который будет содержать почтовый ящик отправителя email-сообщения, на вкладке [Параметры] ([Parameters]) панели настройки свойств процесса выполните действие [Добавить параметр] —> [Текст] ([Add parameters] —> [Text]) и установите следующие свойства параметра (рис. 22):

• [Заголовок] ([Title]) — "Sender Mailbox".
• [Код] ([Code]) — "SenderMailbox".
• [Тип данных] ([Data type]) — выберите "Text (250 characters)".
• [Значение] ([Value]) — нажмите —> [Параметр процесса] ([Process parameter]) и выберите элемент процесса "Sender Mailbox".

Рис. 22. — Добавление параметра процесса

Нажмите [Сохранить] ([Save]).

7. Добавьте методы

Для добавления методов бизнес-процесса на вкладке [Методы] ([Methods]) панели настройки свойств процесса в блоке [Usings] нажмите и в поле [Пространство имён] ([Name Space]) добавьте значение Terrasoft.Mail.Sender. Нажмите [Сохранить] ([Save]).

Таким же способом добавьте следующие пространства имен:

• Terrasoft.Core.Factories
• System.Linq

Сохраните все изменения в дизайнере процессов.

8. Запуск бизнес-процесса

После запуска бизнес-процесса по кнопке [Запустить] ([Run]) будет открыта страница для заполнения параметров email-сообщения (рис. 23).

Рис. 23. — Страница для отправки email-сообщения

Для отправки email-сообщения с явным указанием учетных данных нажмите [Continue].