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 Mail Server

The Module Connect to Mail Server allows you to create or link an email server with which you test email features. This step is mandatory for all Mail Engine 3.0 TestCases.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Connection Name

Specify a unique name for the mail server that you want to create or link.

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

  • Employ POP3 network protocol.

Establish a connection to mailengine.examplecompany.com

Send Mail

The Module Send Mail allows you to send and reply to email 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 email 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 email 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 email.

This ModuleAttribute is optional.

Reply To->Reply Options

Select one o 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

Receive Mail Simple

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

If you want to check the receipt of multiple emails, 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.

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.

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.

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.

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 Attachment To

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

If your email 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.

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

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, 8 a.m. UTC and August 1st, 2019, 8 p.m. UTC.

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 a specific email

Receive Mail Expert

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

If you want to check whether you received a specific, single email, 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 email 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.

Result

Read-only.

Result->ResultCount

Verify the result count of the filter criteria that you specified, i.e. how many emails 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 email that you want to search for and test.

You can search for and test multiple emails. To do so, create a separate node for each email and fill out the Mail Attributes.

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

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

You can use one operation per email. 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 email 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 emails 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 two specific emails.

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

Email 1 must fulfill the following requirements:

  • The recipient received the email specifically between February 1st, 2019, 8 a.m. UTC and February 10th, 2019, 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:\Temp.

Email 2 must fulfill the following requirements:

  • The subject line is Test Email.

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

Search for two specific emails

Reply to an email

You can reply to an email 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 email that you received. For the subject line, it adds the prefix Re: in front of the original email subject.

You can use the Body ModuleAttribute for the content of your reply email. You can also add new attachments. The reply email doesn't contain any attachments from the original email 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