# Read Email

The ReadEmail function will connect to a mail server using either IMAP or POP3.

***

### Properties <a href="#properties" id="properties"></a>

#### Mail server settings <a href="#mail-server-settings" id="mail-server-settings"></a>

**Protocol**

Protocol to use when reading the email.

Select either 'IMAP' or 'POP3'.

**IMAP** (Internet Message Access Protocol) provides access and retrieve mail functions for a remote mail server so the mails can be used locally while retaining them also on the server. Imap sets message flags so that the user can keep track of which messages he or she has already seen, already answered, and so on.

**POP3** (Post Office Protocol) implements the offline mail access model, where mail is retrieved and then deleted from the server where the mailbox resides so it can be used on a local machine. Emails are hence transferred permanently from a central server to one client machine.

**Authentication**

Authentication type to use when connecting to the email server.

Available options:

* **AuthLogin** - Specifies that the mail server uses plain text authentication.
* **AuthCRAM5** - Specifies that the mail server uses MD5 hash authentication [learn more](https://en.wikipedia.org/wiki/CRAM-MD5)
* **AuthNTLM** - Specifies that the mail server uses Windows NT LAN Manager (NTLM) authentication [learn more](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/ntlm-user-authentication)
* **AuthXOAUTH2** - Specifies that the SMTP server uses the OAUTH mechanism for GMAIL [learn more](https://www.emailarchitect.net/eagetmail/sdk/html/object_oauth.htm) or Office365 [learn more](https://linx.software/blog/using-oauth2-to-access-emails/)

**User name**

The user name for the mailbox you wish to access.

**Password/Token**

The password for the mailbox you wish to access.

{% hint style="info" %}
Note:\
When using *AuthXOAUTH2* as Authentication type, enter your *Access Token* here.
{% endhint %}

**Port**

The port number used to access the mailbox.

**Server name**

The IP address, URL or network name of the server.

**Use SSL**

Using SSL (Secure Socket Layer) is more secure as the data is encrypted.

#### Options <a href="#options" id="options"></a>

**Folder**

Only displayed when *IMAP* was selected as Protocol.

The email folder on the server where the mails you wish to retrieve are stored.

**Only unread items**

Only displayed when *IMAP* was selected as Protocol.

A flag to indicate whether only unread mails should be retrieved.

**Mark as read**

Only displayed when *IMAP* was selected as Protocol.

A flag to indicate whether retrieved emails should be marked as 'read'.

**Move to folder**

Only displayed when *IMAP* was selected as Protocol.

A folder to move retrieved emails to.

**Delete after read**

A flag to indicate whether retrieved emails should be deleted from the original folder.

**Body as HTML**

A flag to indicate if the email's body should be retrieved formatted in HTML. Otherwise, the body will be retrieved as unformatted text.

**Attachment options**

Three options are available for attachments.

*None* will ignore attachments.

*SaveToFile* will save the attachments as files to the specified directory. The filepath is an automatic output of this function and can be used to use an attachment later in the process.

*ReturnData* will convert the attachment contents to a string or a List and allow you to use that further down in your process. This option will require you to set the Attachment data property.

**Attachment data**

This property will only display if *ReturnData* was selected for the Attachment options property.

Select either *Text* or *Binary*, depending on the type of data.

*Text* returns a String and *Binary* returns a List\<byte>.

**Save email**

A flag to indicate if the emails should be saved to disk.

**File directory**

Only displayed when the *Save email* property is selected.

The directory where emails and attachments will be saved. For emails, the subject line becomes the filename. Attachments already have filenames that will be used when saving.

If a file of that name already exists, the function will add the year, month, day, hour, second and milliseconds to the filename in this format *yyyy-mm-dd-hh-ss-ffff* to make sure it is unique.

If the filename is too long, it will be truncated.

**Email file type**

Only displayed when the *Save email* property is selected.

The file type used when saving emails to disk.

Two options are available: **eml** [learn more](https://file.org/extension/tnef) and **tnef** [learn more](https://file.org/extension/eml)

#### Regex filters <a href="#regex-filters" id="regex-filters"></a>

[Regex](http://en.wikipedia.org/wiki/Regular_expression) filters allow you to retrieve emails containing specific information.

The regular expression matching is case sensitive by default. Use the [case insensitive mode modifier](http://www.regular-expressions.info/modifiers.html) *(?i)* to force case insensitive matching.

**Filter body**

Text to search for in the *body* of the email.

**Filter from**

Text to search for in the *display name of the sender* of the email.

**Filter from address**

Text to search for in the *address of the sender* of the email.

**Filter subject**

Text to search for in the *subject* of the email.

**Filter to**

Text to search for in the *recipient* of the email.

**Filter cc**

Text to search for in the *cc recipients* of the email.

#### Regex filters operator <a href="#regex-filters-operator" id="regex-filters-operator"></a>

**Filter option**

If you have specified multiple RegEx search criteria, you can define whether these should be chained together with an *AND* or with an *OR*.

*AND* means that all filters need to be true for the mail to be retrieved.

*OR* means that ANY of the filters need to be true for the mail to be retrieved.

***

### Reading Gmail emails <a href="#reading-gmail-emails" id="reading-gmail-emails"></a>

Gmail only uses OAuth2.0 to read and send emails. For more information using the OAUTH mechanism for GMAIL [learn more](https://www.emailarchitect.net/eagetmail/sdk/html/object_oauth.htm) or Office365 [learn more](https://linx.software/blog/using-oauth2-to-access-emails/)

**In Linx Designer**

Set the following properties:

* Protocol: Imap
* Enable SSL
* Port 993
* SMTP server: imap.gmail.com
* User name: your Gmail account (<xxxx@gmail.com>)
* Authentication : OAuth2
* Token : your Gmail token.

**Folders**

Personal folders / labels are accessed by adding the name (including spaces) or parentname/childname (e.g. parent label/child label) in the *Folder* property

While not all functions can be applied to system folders (system labels), all of them can be read. However, the names of these folders are language-dependent and could also change over time. At the time of writing, the system folders below were found to work for English interfaces.

1. Inbox
2. \[Gmail]/All Mail
3. \[Gmail]/Drafts
4. \[Gmail]/Sent Mail
5. \[Gmail]/Spam
6. \[Gmail]/Starred
7. \[Gmail]/Bin

***

### Links <a href="#links" id="links"></a>

[Linx Community: Email plugin configuration](https://community.linx.software/t/email-plugin-configuration/406)

[Linx Community: Email filtering](https://community.linx.software/t/email-filtering/407)

[Wikipedia: IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)

[Wikipedia: POP3](http://en.wikipedia.org/wiki/Post_Office_Protocol)

[Wikipedia: Regular expression](http://en.wikipedia.org/wiki/Regular_expression)

[Regular expression mode modifiers](http://www.regular-expressions.info/modifiers.html)

[Authentication types](https://www.emailarchitect.net/eagetmail/sdk/html/o_serverauthtype.htm)