Sending emails

Guide
Advanced

Attention. Creatio version 7.16 and up supports sending emails using the explicit account credentials

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

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

Sending an email from an existing account algorithm 

To send an email from an existing account:

  1. Create a business process. The process must include Auto-generated page and Script task required elements.
  2. Create a config file for the email.
  3. Add an attachment (optional).
  4. Run the business process to send the email.

Creating a config file for the email 

To create a configuration file of the email, use the Terrasoft.Mail.Sender.EmailMessage class. Populate the parameters below to ensure the validity of your email:

Creating a configuration file of the email
var message = new Terrasoft.Mail.Sender.EmailMessage {
    // Sender email address.
    From = "Sender@email.com",
    // Recipient email addresses.
    To = List<string>{ "first@recepient.co", "second@recepient.co"},
    // Copy optional
    Cc = List<string>{ "first@recepient.co", "second@recepient.co"},
    // Hidden copy optional
    Bcc = List<string>{ "first@recepient.co", "second@recepient.co"},
    // The subject of the email.
    Subject = "Message subject",
    // Email body.
    Body = "Body",
    // Priority, Terrasoft.Mail.Sender.EmailPriority enumeration values.
    Priority = Terrasoft.Mail.Sender.EmailPriority.Normal
};

Adding attachments optional 

You can add attachments to your email. To do this, populate the Attachments field. Attachments are essentially a list of Terrasoft.Mail.Sender.EmailAttachments instances.

Adding attachments to email
// Creating an attachment.
var attachment = new Terrasoft.Mail.Sender.EmailAttachment {
    // Attachment ID.
    Id = new Guid("844F0837-EAA0-4F40-B965-71F5DB9EAE6E"),
    // Attachment name.
    Name = "attachName.txt",
    // Data.
    Data = 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 email parameters and the connection configuration file.

Sending the email
// Sending the configured email message. To ignore access permissions when sending the message. 
// set the ignoreRight parameter to "true".
emailSender.Send(message, ignoreRights);

Sending an email using the explicit account credentials algorithm 

  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.

Creating an instance of the EmailClientFactoryclass
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.

Creating an instance of the EmailSender class
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:

Creating a config file for connecting to the mailbox
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"
};

Attention. The ServiceUrl, UserName, Password, ServerTypeId, SenderMailbox parameters are required.

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:

Creating a config file of the 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.

Adding attachments
// 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 the email
// 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);
Send email from an existing account
Advanced

Example. Create a business process that will open a page with email parameters fields to send an email using an existing account.

Example implementation algorithm 

1. Create a business process 

In the Configuration section execute the Add —> Business process action.

scr_Add_BusinessProcess.png

In the opened Process Designer, set the following values for the properties in the setup area:

  • Title — "Sending emails from existing account".
  • Code — "UsrSendEmailFromExistingUserProcess".
scr_BusinessProcess_settings.png

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:

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

3. Add a button to the page 

To add a Continue button in the Buttons block, click scr_AddButton.png and specify the following parameters:

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

Click Save.

4. Add elements to the page. 

To add an element that will contain the email sender’s mailbox, click scr_AddButton.png in the Page Items block, select the Selection field type and specify the following parameters:

  • Title – "Sender Mailbox".
  • Code – “SenderMailbox”.
  • Data source — select "Mailbox synchronization settings".
  • View — select "Drop down list".
scr_SenderMailbox_settings.png

Click Save.

To add an element that will contain the email recipient’s mailbox, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

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

Click Save.

To add an element that will contain the subject of the email, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “Subject”.
  • Code – “Subject”.
  • Set the Required checkbox.
scr_Subject_settings.png

Click Save.

To add an element that will contain the body of the email, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “Body”.
  • Code – “Body”.
  • Set the Required) checkbox.
scr_Body_settings.png

Click Save.

5. Add a Script task element 

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

Script Task code
var mailBoxSettingId = Get<Guid>("SenderMailbox");
var emailClientFactory = ClassFactory.Get<IEmailClientFactory>(
   new ConstructorArgument("userConnection", UserConnection));
var emailSender = ClassFactory.Get<IEmailSender>(
    new ConstructorArgument("emailClientFactory", emailClientFactory),
    new ConstructorArgument("userConnection", UserConnection));

var entity = UserConnection.EntitySchemaManager.GetInstanceByName("MailboxSyncSettings").CreateEntity(UserConnection);
if (entity.FetchFromDB("Id", mailBoxSettingId, new List<string> { "SenderEmailAddress" })) {
    var senderEmailAddress = entity.GetTypedColumnValue<string>("SenderEmailAddress");
    var message = new Terrasoft.Mail.Sender.EmailMessage {
        From = senderEmailAddress,
        To = Get<string>("Recipient").Split(';').ToList<string>(),
        // Cc = List<string>{ "first@recepient.co", "second@recepient.co"},
        // Bcc = List<string>{ "first@recepient.co", "second@recepient.co"},
        Subject = Get<string>("Subject"),
        Body = Get<string>("Body"),
        Priority = Terrasoft.Mail.Sender.EmailPriority.Normal
    };
    var attachment = new Terrasoft.Mail.Sender.EmailAttachment {
        Id = Guid.NewGuid(),
        Name = "test.txt",
        Data = Encoding.ASCII.GetBytes("some test text")
    };
    message.Attachments.Add(attachment);
    emailSender.Send(message);
}

return true;

6 Add parameters 

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:

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

Click Save.

To add a business process parameter that will contain the subject of the email, execute the Add parameters —> Text action in the Parameters tab of the setup area and specify the following parameter properties:

  • Title – “Subject”.
  • Code – “Subject”.
  • Value – click scr_Value_button.png –> Process parameter and select the “Subject” process element.
scr_SubjectParameter_settings.png

Click Save.

To add a business process parameter that will contain the body of the email, execute the Add parameters —> Text action in the Parameters tab of the setup area and specify the following parameter properties:

  • Title – “Body”.
  • Code – “Body”.
  • Value – click scr_Value_button.png –> Process parameter and select the “Body” process element.
scr_BodyParameter_settings.png

Click Save.

To add a business process parameter that will contain the email sender’s mailbox, execute the Add parameters —> Other —> Unique identifier action in the Parameters tab of the setup area and specify the following parameter properties:

  • Title – "Sender Mailbox".
  • Code – “SenderMailbox”.
  • Value – click scr_Value_button.png –> Process parameter and select the “Sender Mailbox” process element.
scr_SenderMailboxParameter_settings.png

Click Save.

7. Add methods 

To add business process methods, click scr_AddButton.png in the Usings block in the Methods tab of the process designer setup area, and specify Terrasoft.Configuration value in the Name Space field. Click Save.

Using the same method, add the following namespaces:

  • Terrasoft.Mail.Sender
  • Terrasoft.Core.Factories
  • Terrasoft.Core
  • Terrasoft.Mail
  • IntegrationApi
  • System.Linq

Save all changes in the Process Designer.

8. Run the business process 

Attention. To run the business process successfully, make sure that a user account for the email sender is available in the Creatio application. Learn more about adding a user account in the “Integration with the MS Exchange service” block of articles.

After the business process is run using the Run button, a page containing fields for specifying email parameters will open.

src_SendEmailFromExistingAccount.png

To send an email from the corresponding email account, click Continue.

Resources
Package with example implementation
Send email using the explicit account credentials
Advanced

Example. 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.

Example implementation algorithm 

1. Create a business process 

In the Configuration section execute the Add —> Business process action.

scr_Add_BusinessProcess.png

In the opened process designer set the following values for the properties in the setup area:

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

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:

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

3. Add a button to the page 

To add a Continue button, click scr_AddButton.png in the Buttons block and specify the following parameters:

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

Click Save.

4. Add elements to the page. 

To add an element that will contain the email sender’s mailbox, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – "Sender Mailbox".
  • Code – “SenderMailbox”.
  • Set the Required checkbox.
scr_SenderMailbox_settings.png

Click Save.

To add an element that will contain the name of the email sender, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “User Name”.
  • Code – “UserName”.
  • Set the Required checkbox.
scr_UserName_settings.png

Click Save.

To add an element that will contain the password for email sender’s mailbox, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “Password”.
  • Code – “Password”.
  • Set the Required checkbox.
scr_Password_settings.png

Click Save.

To add an element that will contain the mail server address of the email sender, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – "Service Url".
  • Code – “ServiceUrl”.
  • Set the Required checkbox.
scr_ServiceUrl_settings.png

Click Save.

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

  • Title – “Port”.
  • Code – “Port”.
scr_Port_settings.png

Click Save.

To add an element that will contain the cryptographic protocol to ensure a secure connection, click scr_AddButton.png in the Page Items block, select the Boolean type and specify the following parameters:

  • Title – " Use Ssl".
  • Code – “UseSsl”.
scr_UseSsl_settings.png

Click Save.

To add an element that will contain the email recipient’s mailbox, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

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

Click Save.

To add an element that will contain the subject of the email, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “Subject”.
  • Code – “Subject”.
  • Set the Required checkbox.
scr_Subject_settings.png

Click Save.

To add an element that will contain the body of the email, click scr_AddButton.png in the Page Items block, select the Text field type and specify the following parameters:

  • Title – “Body”.
  • Code – “Body”.
  • Set the Required checkbox.
scr_Body_settings.png

Click Save.

To add an element that will contain the type of the email sender’s provider, click scr_AddButton.png in the Page Items block, select the Selection field type and specify the following parameters:

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

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:

Script Task code
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")
};
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,
    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);
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:

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

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:

  • Title – “Port”.
  • Code – “Port”.
  • Value – click scr_Value_button.png –> Process parameter and select the “Port” process element.
scr_PortParameter_settings.png

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

Click Save.

7. Add methods 

To add business process methods, click scr_AddButton.png 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.

scr_SendEmailWithExplicitCredentials.png

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

Resources
Package with example implementation