////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
:documentationPath: /pipeline/transforms/
:language: en_US
:description: The Email Messages Input transform allows you to retrieve messages and their attachments from a mail server using the POP3, IMAP or MBOX standard protocols.

= image:transforms/icons/mailinput.svg[Email Messages Input transform Icon, role="image-doc-icon"] Email Messages Input

[%noheader,cols="3a,1a", role="table-no-borders" ]
|===
|
== Description

The Email Messages Input transform allows you to retrieve messages and their attachments from a mail server using the POP3, IMAP or MBOX standard protocols.

|
== Supported Engines
[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
!===
!Hop Engine! image:check_mark.svg[Supported, 24]
!Spark! image:question_mark.svg[Maybe Supported, 24]
!Flink! image:question_mark.svg[Maybe Supported, 24]
!Dataflow! image:question_mark.svg[Maybe Supported, 24]
!===
|===

== Options

=== General

On this tab you will find the general mail server connection settings:

[options="header"]
|===
|Option|Description
|Transform name|Name of the transform.
|Source host|The mail server host
|Use SSL?|Check this option if your server needs an SSL connection
|Use XOAUTH2 |If checked XOAuth2 will be used to authenticate with the server.
|Username|The username of the mailbox to connect to
|Password|The password to use
|Use proxy?|Check this option if you want to connect through a proxy.
|Proxy username|The username to connect to the proxy with
|Fetch in batches?|Enable this option if you want to retrieve larger volumes of mails in batches
|Ignore errors reading fields|Sometimes a server doesn't support the retrieval of a particular piece of information.
Enable this option to ignore these errors.
|Protocol|Specify either standard protocol POP3, IMAP or MBOX to retrieve the mails
|Test Connection button|This will simply try to connect to the mail server with the specified settings.
This button does not retrieve mails.
|===

=== Settings

**POP3 settings**

[options="header"]
|===
|Option|Description
|Retrieve|Specify either "All emails" or "Retrieve first... emails"
|Retrieve the ... first emails|Allows you to specify how many mails you want to retrieve at most in one go
|===

**IMAP settings**

[options="header"]
|===
|Option|Description
|Get folder from field|Enable this option to allow the IMAP folder name to be present in an input field of this transform.
|Folder field|The folder field in case the option above is enabled.
|IMAP folder|The IMAP folder to retrieve mails from
|Test folder... button|Use this to test if the folder is valid
|Open button|use this to select the IMAP folder
|Include subfolders|Check this option to also retrieve mails from sub-folders
|Retrieve|Specify which mails to retrieve: Get all, new, old, read, unread, flagged, not flagged, draft, not draft, answered or not answered messages.
|Retrieve the first ... emails|Specify how many emails to retrieve at most
|===

**Batch settings**

[options="header"]
|===
|Option|Description
|Batch size|Number of emails to retrieve at once in one batch
|Start at message number|The first message number to start retrieving at
|End at message number|The last message number to end retrieving with
|===

=== Filters

These are the filters you can set on the header of the mail message.
Mail for which the header matches your filter will be retrieved, the rest is ignored.

[options="header"]
|===
|Option|Description
|Sender (FROM)|Only retrieve
|===
