Mail Modules

The folder TBox XEngines->Mail in the Standard subset contains Modules that perform specific tasks for the Mail Engine 3.0.

Connect to Exchange Server

The Module Connect to Exchange Server allows you to connect to a Microsoft Exchange Server to test e-mail features. You can use this step for the exchange server and mail server TestCases.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Specify a unique name for the exchange server that you want to connect to.

The Mail Engine 3.0 uses this connection name in subsequent TestSteps to connect to the exchange server.

Authentication Type

Choose the authentication method to connect to the Exchange Server endpoint. The following values are available:

  • Basic (legacy): uses basic authentication to connect with the endpoint. The result of associated TestSteps does not depend on credential validation. Note that Microsoft has announced the deprecation of this endpoint type.

  • OAuth: uses modern authentication via OAuth2 to connect with the endpoint. The result of associated TestSteps depends on credential validation (token acquisition). If the validation fails, so does the TestCase. Registration with the Microsoft identity platform is required.

In your associated TestSteps, always use this ModuleAttribute with ActionMode Select.

Username

User name of the exchange server account.

Password

Password of the user account.

App Id

If you select OAuth as the Authentication Type, specify the Application (client) ID of your registration with the Microsoft identity platform.

Tenant Id

If you select OAuth as the Authentication Type, specify the Directory (tenant) ID of your registration with the Microsoft identity platform.

Exchange Web Services Url

Optionally, specify the address of exchange server.

Use the format https://<mail-server>/ews/exchange.asmx and replace <mail-server> with the address of your exchange server.

Otherwise, the Autodiscover service in the exchange server specifies this ModuleAttribute automatically if it can be inferred from the username.

Tricentis Tosca supports Office 365. If Azure Multi-Factor Authentication (MFA) is enabled for your account, you need to create a new app password for two-step verification (2FA). For more information, see the Microsoft documentation: Manage app passwords for two-step verification.

In this example, you establish a connection with the name SampleConnection that connects to the exchange server exchangemail.com.

Tricentis recommends that you use HTTPS for any request you send to an EWS endpoint to secure communication between your application and the exchange server.

Establish a connection to exchange server

The actual connection happens during sending or receiving email.

Connect to Mail Server

The Module Connect to Mail Server allows you to specify an e-mail server with which you test e-mail features. If there are no credentials TestStep value, the currently logged in Windows user is used to connect to the Mail Server.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Specify a unique name for the mail server that you want to connect to.

The Mail Engine 3.0 uses this connection name in later TestSteps to connect to the mail server.

Mail Server

IP address or FQDN (Fully Qualified Domain Name) of the mail server.

Username

User name of the account with which you access the mail server.

Password

Password of the specified user name.

Port

Port number through which you connect.

Ensure the port is open and not blocked by the firewall.

Enable Security

Select whether you want to use a secure connection with SSL/TLS certificates during e-mail operations.

The available values are:

  • True: use a secure connection.

  • False: don't use a secure connection.

Protocol

Specify the network protocol you want to use.

The available values are:

  • SMTP (Simple Mail Transfer Protocol)

  • POP3 (Post Office Protocol)

  • IMAP (Internet Message Access Protocol)

In this example, you establish a connection with the name SampleConnection, which connects to the mail server mailengine.examplecompany.com.

This connection has the following specifications:

  • Use the credentials of John Doe to connect.

  • Connect via port 110.

  • Don't use a secure connection.

  • Use the POP3 Email protocol.

Use the following TestStep to define your connection to the Mail Server.

Establish a connection to mailengine.examplecompany.com

The actual connection happens during sending or receiving email.

Receive Mail Simple

The Module Receive Mail Simple allows you to check whether you received a specific, single e-mail. This functionality supports POP3 or IMAP protocols only.

If you want to check the receipt of multiple e-mails, use the Module Receive Mail Expert.

The Module Receive Mail Simple has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Name of the connection that you defined. Use ActionMode Input.

From Address

Specify the email address of the sender.

This ModuleAttribute is optional.

From Name

Specify the name of the sender.

This ModuleAttribute is optional.

To

Specify a recipient.

This ModuleAttribute is optional.

Cc

Specify a copy recipient.

This ModuleAttribute is optional.

From Date/Time

Specify the start date and time of the search period.

This ModuleAttribute is optional.

To Date/Time

Specify the end date and time of the search period.

This ModuleAttribute is optional.

Subject

Specify the subject line.

This ModuleAttribute is optional.

Body

Enter the message body.

The default format in Mail Engine 3.0 is plain text. If Tosca doesn't return the expected results, select the HTML property to switch to HTML format. Use wildcards to ensure that the Mail Engine 3.0 only verifies the body text, not the HTML tags. Note that the value entries are case sensitive.

This ModuleAttribute is optional.

Attachment Name

Specify the file name of the attachment.

You can have multiple attachments. In the background, the Mail Engine 3.0 stores all attachment names as one string, separated by semicolons.

If you want to verify whether a specific attachment exists, use leading and trailing wildcards. The wildcards ensure that the Mail Engine 3.0 only verifies the existence of the one attachment, not the entire string.

For example, if you have several attachments, but only want to verify whether the attachment TestAttachment.txt exists, enter *TestAttachment.txt*.

You can also buffer attachment names. However, you can only buffer the entire string, not individual attachment names.

This ModuleAttribute is optional.

Folder

This functionality is supported by IMAP servers only.

Specify the folder structure path, for example INBOX.TestFolder. The separator depends on the mail server that you use.

Use ActionMode Input.

The server settings determine the exact folder names, including lowercase and uppercase letters.

This ModuleAttribute is optional.

Save Attachments To

Specify the path to the folder where you want to save the attachment. Use ActionMode Input.

If your e-mail contains several attachments, all of them are saved to this folder.

If the folder already contains attachments with the same name, the Mail Engine 3.0 overwrites the existing files.

This ModuleAttribute is optional.

Save Mail

Specify a unique name for the mail that you want to save.

In the Send Mail module this can be used to send a reply message.

Number of Emails to examine

Specify the maximum number of e-mails to examine.

This ModuleAttribute is optional.

You can use regular expressions and wildcards.

Use ActionModes

Unless otherwise specified in the descriptions of the ModuleAttributes in the table above, you can use the following ActionModes:

  • ActionMode Input to define base search criteria.

  • ActionMode Constraint to further narrow down the search of all e-mails that fit the base search criteria.

  • ActionMode Verify to verify data.

  • ActionMode Buffer to save data to a buffer.

In this example, you check whether you have received a specific, single email with the following content: "Congratulations on your research grant".

To do so, you use the connection SampleConnection that you established earlier (see chapter "Connect to Mail Server").

The base search criteria are the following:

  • The sender is mark.kim@examplecompany.com.

  • The recipient is lisa.miller@examplecompany.com.

  • The recipient received the email between July 1st, 2019, 6 a.m. UTC and August 1st, 2019, 8 p.m. UTC.

    For this, you first have to define ToscaDateFormat as follows. For more information see "Settings - Dynamic Temporal Expressions".

    Define ToscaDateFormat

Out of all emails that fit these criteria, you are looking for the one that fulfills the following requirements:

  • The subject line is Research requirements.

  • It has an attachment: specifications.pdf.

Once the Mail Engine 3.0 has found the email, you want to perform the following actions:

  • Verify whether the message body contains the string "Congratulations on your research grant".

  • Write the name of all email attachments to the Buffer AttachmentsResearch.

Search for an email with formatted content

 

Search for an email with content

Receive Mail Expert

The Module Receive Mail Expert allows you to check whether you received specific e-mails. This functionality supports POP3 or IMAP protocols only.

If you want to check whether you received a specific, single e-mail, use the Module Receive Mail Simple.

The Module Receive Mail Expert has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Name of the connection that you defined. Use ActionMode Input.

Search criteria

Read-only.

Search criteria->From Address

Specify the e-mail address of the sender.

This ModuleAttribute is optional.

Search criteria->From Name

Specify the name of the sender.

This ModuleAttribute is optional.

Search criteria->To

Specify a recipient.

This ModuleAttribute is optional.

Search criteria->Cc

Specify a copy recipient.

This ModuleAttribute is optional.

Search criteria->Subject

Specify the subject line.

This ModuleAttribute is optional.

Search criteria->Attachment Name

Specify the file name of the attachment.

You can have multiple attachments. In the background, the Mail Engine 3.0 stores all attachment names as one string, separated by semicolons.

If you want to verify whether a specific attachment exists, use leading and trailing wildcards. The wildcards ensure that the Mail Engine 3.0 only verifies the existence of the one attachment, not the entire string.

For example, if you have several attachments, but only want to verify whether the attachment TestAttachment.txt exists, enter *TestAttachment.txt*.

You can also buffer attachment names. However, you can only buffer the entire string, not individual attachment names.

This ModuleAttribute is optional.

Search criteria->Body

Enter the message body.

The default format in Mail Engine 3.0 is plain text. If Tosca doesn't return the expected results, select the HTML property to switch to html format. Use wildcards to ensure that the Mail Engine 3.0 only verifies the body text, not the HTML tags.

This ModuleAttribute is optional.

Search criteria->From Date/Time

Specify the start date and time of the search period.

The Mail Engine 3.0 uses UTC time. Consequently, you need to enter the start time and date in UTC time.

This ModuleAttribute is optional.

Search criteria->To Date/Time

Specify the end date and time of the search period.

The Mail Engine 3.0 uses UTC time. Consequently, you need to enter the end time and date in UTC time.

This ModuleAttribute is optional.

Search criteria->Folder

This functionality is supported by IMAP servers only.

Specify the folder structure path, for example INBOX.TestFolder. The separator depends on the mail server that you use.

Use ActionMode Input.

The server settings determine the exact folder names, including lowercase and uppercase letters.

This ModuleAttribute is optional.

Search criteria->Number of Emails to examine

Specify the maximum number of e-mails to examine.

This ModuleAttribute is optional.

Result

Read-only.

Result->ResultCount

Verify the result count of the filter criteria that you specified, i.e. how many e-mails the specific filter produces.

To do so, enter the expected number and use ActionMode Verify.

Result->Mail

Each Mail node under Result represents an individual e-mail that you want to search for and test.

You can search for and test multiple e-mails. To do so, create a separate node for each e-mail and fill out the Mail Attributes.

You can choose the following criteria from the Mail drop-down menu:

  • To verify the first e-mail, enter $1.

  • To specify the e-mail number using a dollar sign as a prefix, enter $<n> where <n> is the respective number.

  • To verify the last e-mail, enter $last.

Result->Mail->Mail Attributes

Specify further search criteria to narrow down the search.

You can choose the following criteria from the Mail Attributes drop-down menu:

  • From Name

  • From Address

  • To

  • Cc

  • Subject

  • Body

  • From Date/Time

  • To Date/Time

  • Attachment Name

Result->Mail->Mail Operations

You can select the following operations from the Mail Operations drop-down menu:

  • Delete: deletes the e-mail.

  • Move To: moves the e-mail to an existing folder. Only IMAP servers support this operation.

  • Read: marks the e-mail as read.

  • Unread: marks the e-mail as unread.

You can use one operation per e-mail. Use ActionMode Select.

Result->Mail->Save Attachments To

Specify the path to the folder where you want to save the attachment. Use ActionMode Input.

If your e-mail contains several attachments, all of them are saved to this folder.

If the folder already contains attachments with the same name, the Mail Engine 3.0 overwrites the existing files.

This ModuleAttribute is optional.

Result->Mail->Save Mail

Specify a unique name for the mail that you want to save.

In the Send Mail module this can be used to send a reply message.

You can use regular expressions and wildcards.

Use ActionModes

Unless otherwise specified in the descriptions of the ModuleAttributes in the table above, you can use the following ActionModes:

  • ActionMode Input to define base search criteria.

  • ActionMode Constraint to further narrow down the search of all e-mails that fit the base search criteria.

  • ActionMode Verify to verify data.

  • ActionMode Buffer to save data to a buffer.

In this example, you check whether you have received specific emails.

To do so, you use the connection SampleConnection that you established earlier (see chapter "Connect to Mail Server").

The base search criteria are the following:

  • The sender is mark.kim@examplecompany.com.

  • The recipient is lisa.miller@examplecompany.com.

  • The recipient received the email some time within the last year, calculated back from the current date.

Out of all emails that fit these criteria, you are looking for three specific emails.

You also want to check that only three emails match all specified criteria. To do so, you verify the result count.

Email 1 must fulfill the following requirements:

  • The subject line is Test Email 1.

  • The recipient received the email specifically between February 1st, 2020, 8 a.m. UTC and February 10th, 2020, 8 p.m. UTC.

  • amy.wu@examplecompany.com is in Cc.

Furthermore, you want to perform the following actions on Email 1:

  • Save the subject line to a buffer named SubjectLineBuffer.

  • Save all email attachments to C:\Source.

Email 2 must fulfill the following requirements:

  • The subject line is Test Email 2.

  • The message body contains the string This is a test email.

Furthermore, you want to perform the following actions on Email 2:

  • Verify whether the email contains an attachment: TestAttachment.txt.

  • Delete the email.

Email 3 must fulfill the following requirements:

  • This must be the latest email matching the Search Criteria.

  • The subject line is Test Email 3.

Furthermore, you want to perform the following actions on Email 3:

  • Delete the email.

Search for three specific emails

Reply to an e-mail

You can reply to an e-mail that you received and saved with the Send Mail Module.

To do so, you have to populate all reply fields with valid values as shown in the example below. The Mail Engine populates the subject and address fields with values from the original e-mail that you received. For the subject line, it adds the prefix Re: in front of the original e-mail subject.

You can use the Body ModuleAttribute for the content of your reply e-mail. You can also add new attachments. The reply e-mail doesn't contain any attachments from the original e-mail that you reply to.

In this example, you reply to an email message. First, you need to search for the email you want to reply to and save it.

You have the following base search criteria:

  • The sender is mark.kim@examplecompany.com.

  • One of the recipients is lisa.miller@examplecompany.com.

  • The recipient received the email between July 1st, 2019, 8 am. UTC and August 1st, 2019, 8 pm. UTC.

Multiple emails fit these criteria, so you add the following criteria:

  • The subject line is Research requirements.

  • The email contains the attachment specifications.pdf.

Once the Mail Engine 3.0 has found the email, you want to perform the following actions:

  • Verify whether the message body contains the string Congratulations on your research grant.

  • After every verification was successful, save the email as SavedEmail.

Search for a specific email and save it

Now you can send the reply message::

  • You use the connection SampleSendConnection.

  • The sender is Lisa Miller with the address lisa.miller@examplecompany.com.

  • The subject line is This is a test email.

  • You enter the following message body which is sent as HTML: Thank you for your kind words.

  • You attach the requirements.doc file which is located at D:\.

  • You enter SavedEmail as the email you want to reply to.

  • You select Reply as the reply option.

Send a reply email

Send Mail

The Module Send Mail allows you to send and reply to e-mail messages via Simple Mail Transfer Protocol (SMTP).

It has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Enter the name of the connection that you defined.

From->Address

Specify the e-mail address of the sender.

From->Name

Specify the name of the sender.

This ModuleAttribute is optional.

Subject

Specify the subject line.

This ModuleAttribute is optional.

To

Specify a recipient. You can add multiple recipients.

Cc

Specify a copy recipient. You can add multiple recipients in separate module attributes.

This ModuleAttribute is optional.

Bcc

Specify a blind copy recipient. You can add multiple recipients in separate module attributes.

This ModuleAttribute is optional.

Body

Enter the message body. The body of the sent e-mail uses HTML format.

This ModuleAttribute is optional.

Attachment

Specify the full file path to the attachment. You can add multiple attachments in separate module attributes.

This ModuleAttribute is optional.

Reply To->Mail To Reply

Name of the saved e-mail.

This ModuleAttribute is optional.

Reply To->Reply Options

Select one of the following options from the Reply Options drop-down menu:

  • Reply: only the sender receives the reply.

  • ReplyAll: every addressee receives the reply.

This ModuleAttribute is optional.

In this example, you send an email message with the following specifications:

  • Use the connection SampleConnection.

  • The sender is Sylvia Jones with the address sylvia.jones@examplecompany.com.

  • The subject line is This is a test email.

  • The recipient is HR@examplecompany.com.

  • admin.linda@examplecompany.com and admin.bob@examplecompany.com are in Cc.

  • Enter the following message body: This is a test.

  • Attach the files test1.txt and test2.txt, which are both located at C:\Temp.

Send an email