Sending emails using the explicit account credentials

Introduction

In Creatio, you can send emails using both customer and developer means. By developer means, you can send emails:

• Using an existing account
• Using the explicit account credentials

This article covers sending emails using explicit account credentials. Read more about sending emails using an existing account in the “Sending emails from existing account" article.

Sending an email using the explicit account credentials is done by using a business process. To set up a business process, use the [Auto-generated page] and [Script task] elements.

Preparing and sending an email

To send an email using the explicit account credentials:

1. Create a business process. The process must include [Auto-generated page] and [Script task] required elements.
2. Create an instance of the EmailClientFactory class.
3. Create an instance of the EmailSender class.
4. Create a config file for connecting to the mailbox.
5. Create a config file of the email.
6. Add an attachment (if applicable).
7. Run the business process to send the email.

Creating an instance of the EmailClientFactory class.

To create an instance of the EmailClientFactory class, make sure you have UserConnection established.

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

Creating an instance of the EmailSender class.

To create an instance of the EmailSender class, pass the created EmailClientFactory instance and the UserConnection to the constructor.

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

Creating a config file for connecting to the mailbox

To create a config file for connecting to the mailbox, use the EmailContract.DTO.Credentials class. Populate the following parameters:

var credentialConfig = new EmailContract.DTO.Credentials {
    // Outbound mailserver IP address or domain
    ServiceUrl = "mail service host",
    // Can be left empty for some protocols
    Port = "Port",
    // Use SSL to encrypt the connection.
    UseSsl = false,
    // Mailbox user name
    UserName = "EmailUserName",
    // Mailbox user password
    Password = "UserPassword",
    // Mail server type (Exchange or IMAP/SMTP)
    ServerTypeId = EmailDomain.IntegrationConsts.ExchangeMailServerTypeId ||
             EmailDomain.IntegrationConsts.ImapMailServerTypeId,
    // Sender mailbox
    SenderEmailAddress = "sender@test.com"
};

Creating a config file of the email

To create a configuration file of the email that you are sending, use the EmailContract.DTO.Email class. Populate the parameters shown below to ensure the validity of your email:

var message = new EmailContract.DTO.Email {
    // Sender email address.
    Sender = "Sender@email.com",
    // Recipient email addresses.
    Recepients = List<string>{ "first@recepient.co", "second@recepient.co"},
    // The subject of the email.
    Subject = "Message subject",
    // Email body.
    Body = "Body",
    // Priority, EmailContract.EmailImportance enumeration values.
    Importance = EmailContract.EmailImportance.High
};

Adding attachments (if applicable)

You can add attachments to your email. To do this, populate the [Attachments] field. Attachments are essentially a list of EmailContract.DTO.Attachment instances.

// Creating an attachment.
var attachment = new EmailContract.DTO.Attachment {
    Name = "FileName",
    Id = "844F0837-EAA0-4F40-B965-71F5DB9EAE6E"
};
// Setting data for the attachment
attachment.SetData(byteData);
// Adding the attachment to the message.
message.Attachments.Add(attachment);

Sending the email

To send the email, use the Send method of the EmailSender class with the passed arguments of the email and the connection configuration file.

// Sending a configured email message with connection parameters
// for the mailbox of the sender To ignore access permissions when sending the message. 
// set the ignoreRight parameter to "true".
emailSender.Send(message, credentialConfig, ignoreRights);

Case description

Create a business process that will open a page containing fields mapped to the email parameters to send an email using the explicit account credentials.

Source code

You can download the package with case implementation using the following link.

Case implementation algorithm

1. Create a business process

In the [Configuration] section execute the [Add] –> [Business process] action (Fig. 1).

Fig. 1. [Add] –> [Business process] action

In the opened process designer set the following values for the properties in the setup area (Fig. 2):

• [Title] — "Sending emails using the explicit account credential".
• [Code] – “UsrSendEmailWithCredentialsProcess”.

Fig. 2. The properties of the business process

2. Add the [Auto-generated page] element

The [Auto-generated page] element enables the process to open an arbitrary page created by the user. For this element, add “Filling parameters” as a caption and set the following properties (Fig. 3):

• [Page title] — "Fill parameters for sending Email".
• [To whom should the page be shown?] – select [Formula] and specify [#System variable.Current user contact#].

Fig. 3. Auto-generated page properties

3. Add a button to the page

To add a [Continue] button, click in the [Buttons] block and specify the following parameters (Fig. 4):

• [Caption] — "Continue".
• [Code] – “ContinueButton”.
• [Style] — select "Green".
• Set the [Active] checkbox.
• Set the [Performs value validation] checkbox.

Fig. 4. Adding a button to the auto-generated page

Click [Save].

4. Add elements to the page.

To add an element that will contain the email sender’s mailbox, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 5):

• [Title] – "Sender Mailbox".
• [Code] – “SenderMailbox”.
• Set the [Required] checkbox.

Fig. 5. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the name of the email sender, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 6):

• [Title] – “User Name”.
• [Code] – “UserName”.
• Set the [Required] checkbox.

Fig. 6. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the password for email sender’s mailbox, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 7):

• [Title] – “Password”.
• [Code] – “Password”.
• Set the [Required] checkbox.

Fig. 7. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the mail server address of the email sender, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 8):

• [Title] – "Service Url".
• [Code] – “ServiceUrl”.
• Set the [Required] checkbox.

Fig. 8. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the port number of the email sender’s mail provider, click in the [Page Items] block, select the [Integer] type and specify the following parameters (Fig. 9):

• [Title] – “Port”.
• [Code] – “Port”.

Fig. 9. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the cryptographic protocol to ensure a secure connection, click in the [Page Items] block, select the [Boolean] type and specify the following parameters (Fig. 10):

• [Title] – " Use Ssl".
• [Code] – “UseSsl”.

Fig. 10. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the email recipient’s mailbox, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 11):

• [Title] — "Recipient (many recipients separated by semicolon ";")".
• [Code] – “Recipient”.
• Set the [Required] checkbox.

Fig. 11. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the subject of the email, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 12):

• [Title] – “Subject”.
• [Code] – “Subject”.
• Set the [Required] checkbox.

Fig. 12. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the body of the email, click in the [Page Items] block, select the [Text field] type and specify the following parameters (Fig. 13):

• [Title] – “Body”.
• [Code] – “Body”.
• Set the [Required] checkbox.

Fig. 13. Adding an element to the auto-generated page

Click [Save].

To add an element that will contain the type of the email sender’s provider, click in the [Page Items] block, select the [Selection field] type and specify the following parameters (Fig. 14):

• [Title] — "Type of mail server".
• [Code] – “ServerTypeId”.
• Set the [Required] checkbox.
• [Data source] — select "Mail service provider type".
• [View] — select "Drop down list".

Fig. 14. Adding an element to the auto-generated page

Click [Save].

5. Add a [ScriptTask] element

Set the value of the [Title] property of the [Script task] element to “Send Email”. The element must execute the following program code:

// Создание экземпляра 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 Add parameters

To add a business process parameter that will contain the address of the sender’s mail server, execute the [Add parameters] —> [Text] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 15):

• [Title] – "Service Url".
• [Code] – “ServiceUrl”.
• [Value] – click –> [Process parameter] and select the “Service Url” process element.

Fig. 15. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the port number of the sender’s email provider, execute the [Add parameters] —> [Integer] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 16):

• [Title] – “Port”.
• [Code] – “Port”.
• [Value] – click –> [Process parameter] and select the “Port” process element.

Fig. 16. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the cryptographic protocol for a secure connection, execute the [Add parameters] —> [Boolean] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 17):

• [Title] – " Use Ssl".
• [Code] — " UseSsl”.
• [Value] – click –> [Process parameter] and select the “ Use SSL” process element.

Fig. 17. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the email sender’s name, execute the [Add parameters] —> [Text] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 18):

• [Title] – “User Name”.
• [Code] – “UserName”.
• [Data type] – select “Text (250 characters)”.
• [Value] – click –> [Process parameter] and select the “User Name” process element.

Fig. 18. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the password for the email sender’s mailbox, execute the [Add parameters] —> [Text] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 19):

• [Title] – “Password”.
• [Code] – “Password”.
• [Data type] – select “Text (250 characters)”.
• [Value] – click –> [Process parameter] and select the “Password” process element.

Fig. 19. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the email recipient’s mailbox, execute the [Add parameters] —> [Text] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 20):

• [Title] – “Recipient”.
• [Code] – “Recipient”.
• [Value] – click –> [Process parameter] and select the “Recipient (many recipients separated by semicolon ";")” process element.

Fig. 20. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the type of the email sender’s mail provider, execute the [Add parameters] —> [Other] —> [Unique identifier] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 21):

• [Title] — "Type of mail server".
• [Code] – “ServerTypeId”.
• [Value] – click –> [Process parameter] and select the “Type of mail server” process element.

Fig. 21. Adding a process parameter

Click [Save].

To add a business process parameter that will contain the email sender’s mailbox, execute the [Add parameters] —> [Text] action in the [Parameters] tab of the setup area and specify the following parameter properties (Fig. 22):

• [Title] – "Sender Mailbox".
• [Code] – “SenderMailbox”.
• [Data type] – select “Text (250 characters)”.
• [Value] – click –> [Process parameter] and select the “Sender Mailbox” process element.

Fig. 22. Adding a process parameter

Click [Save].

7. Add methods

To add business process methods, click in the [Usings] block in the [Methods] tab of the process designer setup area, and specify Terrasoft.Mail.Sender value in the [Name Space] field. Click [Save].

Using the same method, add the following namespaces:

• Terrasoft.Core.Factories
• System.Linq

Save all changes in the Process Designer.

8. Business process launch

After the business process is run using the [Run] button, a page containing fields for specifying email parameters will open (Fig. 23).

Fig. 23. The page for preparing an email

To send an email using the explicit account credentials, click [Continue].