# Email (IMAP)

Read, search and manage email in an IMAP mailbox.

## Connect Email (IMAP)

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `imap` and choose **Email (IMAP)**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for **IMAP server**, **Port**, **Email**, **Password**, **Use TLS** and **Upgrade with STARTTLS (port 143 only)**.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Email (IMAP)**. The trigger uses the same connection as the steps.

### New Email

Fires once for each email that arrives in the mailbox, oldest first. It remembers the newest email it has delivered, so mail that was already in the folder never fires: not when newer mail is moved away, nor when an email is moved out and back.

- **Mailbox · Optional**: The folder to watch for new emails, such as INBOX. Default: INBOX.
- **Max per Poll · Optional**: The most new emails one poll delivers; any more arrive on the next poll, oldest first. Capped at 500. Default: 25.
- **Include Body · Optional**: Fetch and parse the text/HTML body and list the attachments. On by default.
- **Include Attachment Content · Optional**: Return each attachment's bytes as base64 on `attachments[].content`, so a later step can save or forward the file. Only applies when Include Body is on. Attachments over 5 MB keep their metadata and say why the content is missing. Off by default.

A later step can use its data, such as `{{trigger.attachments}}`, `{{trigger.date}}`, `{{trigger.from}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Email (IMAP)

Add an **Email (IMAP)** step and choose what it does. Choose a row to see its fields.

- [Fetch Emails](https://docs.gorunner.io/apps/email-imap#fields-f-fetch): Connect to an IMAP server and fetch recent or matching emails from a mailbox.
- [Mark Email as Read/Unread](https://docs.gorunner.io/apps/email-imap#fields-f-mark-read): Set or clear the read (\Seen) flag on one email.
- [Move Email](https://docs.gorunner.io/apps/email-imap#fields-f-move-email): Move one email to another folder: the usual way to file mail once a workflow has processed it.
- [Delete Email](https://docs.gorunner.io/apps/email-imap#fields-f-delete-email): Flag one email as deleted and (by default) purge it from the folder.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- GoRunner Cloud reaches servers on the public internet only. On a self-hosted installation, an admin can allow private addresses with `WORKFLOW_PRIVATE_NETWORKS`.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Email (IMAP) is `pieceId: "imap"` with the actions `fetch`, `mark_read`, `move_email`, `delete_email`. Its trigger is `imap` / `new_email`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

What each action does outside the run: `fetch` reads_external, `mark_read` writes_external, `move_email` writes_external, `delete_email` writes_external. See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Email (IMAP) › Fetch Emails

Connect to an IMAP server and fetch recent or matching emails from a mailbox.

- **IMAP Host · Optional**: Only for steps without a connection: the address of your email provider's incoming mail server, such as imap.gmail.com. Leave blank when a connection is attached.
- **Port · Optional**: Only for steps without a connection: 993 for implicit TLS, 143 for plain or STARTTLS. A connection's own port always wins. Default: 993.
- **Username · Optional**: Only for steps without a connection: the login name for the mailbox, usually your full email address. Leave blank when a connection is attached.
- **Password · Optional**: Only for steps without a connection: account password or app password. Prefer a connection: a password typed here is stored in the workflow definition.
- **Mailbox · Optional**: The folder to read emails from, such as INBOX, Sent, or Archive. Default: INBOX.
- **Which Emails · Optional**: Which emails to pull. "Most recent N" has no memory: every run returns the same newest emails again. To handle each email once, start the workflow with this app's "New Email" trigger instead of a Schedule. Options: Most recent N (re-delivers every run), Unread (unseen), Since N days ago. Default: Most recent N (re-delivers every run).
- **Since (days ago) · Optional**: How many days back to look for emails, such as 7 fetches emails from the last week. The server matches whole days, so the window can reach ~24 hours further back than you asked. Default: 7. Shows when **Which Emails** is **Since N days ago**.
- **Max Emails · Optional**: Most recent N matching emails. Capped at 500 per run (0 = as many as the cap allows); when more matched, the step's `truncated` output is true and `totalMatched` says how many there were. Default: 10.
- **Include Body · Optional**: Fetch and parse the text/HTML body and list the attachments. On by default.
- **Mark as Read · Optional**: Mark the fetched emails as read on the server. This happens in this step, before any later step runs. If a later step fails, the emails are already consumed and a retry will not see them again. To acknowledge only after the work succeeded, leave this off and add a "Mark Email as Read" step at the end of the workflow. Off by default.
- **Include Attachment Content · Optional**: Return each attachment's bytes as base64 on `attachments[].content`, so a later step can save or forward the file. Only applies when Include Body is on. Attachments over 5 MB keep their metadata and say why the content is missing. Off by default.
- **Use TLS · Optional**: Implicit TLS (port 993). Off = the connection starts unencrypted on port 143. On by default.
- **Upgrade with STARTTLS · Optional**: With Use TLS off, encrypt the port-143 connection with STARTTLS before sending the password. Turn this on for any real server on port 143. Otherwise the mailbox password crosses the network in the clear. Off by default.
- **Ignore TLS Cert Errors · Optional**: Accept self-signed / mismatched certificates. Off by default.

### Email (IMAP) › Mark Email as Read/Unread

Set or clear the read (\Seen) flag on one email. Place it after your processing steps so mail is only acknowledged once the work succeeded.

- **IMAP Host · Optional**: Only for steps without a connection: the address of your email provider's incoming mail server, such as imap.gmail.com. Leave blank when a connection is attached.
- **Port · Optional**: Only for steps without a connection: 993 for implicit TLS, 143 for plain or STARTTLS. A connection's own port always wins. Default: 993.
- **Username · Optional**: Only for steps without a connection: the login name for the mailbox, usually your full email address. Leave blank when a connection is attached.
- **Password · Optional**: Only for steps without a connection: account password or app password. Prefer a connection: a password typed here is stored in the workflow definition.
- **Mailbox · Optional**: The folder the email is in. A UID only means something inside one folder. Default: INBOX.
- **Message UID · Optional**: The email's UID, normally mapped from a fetch or trigger step, such as {{steps.fetch_mail.emails[0].uid}}.
- **Mark as Read · Optional**: On marks the email read; off marks it unread again (the way to hand an email back after a failure). On by default.
- **Use TLS · Optional**: Implicit TLS (port 993). Off = the connection starts unencrypted on port 143. On by default.
- **Upgrade with STARTTLS · Optional**: With Use TLS off, encrypt the port-143 connection with STARTTLS before sending the password. Turn this on for any real server on port 143. Otherwise the mailbox password crosses the network in the clear. Off by default.
- **Ignore TLS Cert Errors · Optional**: Accept self-signed / mismatched certificates. Off by default.

### Email (IMAP) › Move Email

Move one email to another folder: the usual way to file mail once a workflow has processed it.

- **IMAP Host · Optional**: Only for steps without a connection: the address of your email provider's incoming mail server, such as imap.gmail.com. Leave blank when a connection is attached.
- **Port · Optional**: Only for steps without a connection: 993 for implicit TLS, 143 for plain or STARTTLS. A connection's own port always wins. Default: 993.
- **Username · Optional**: Only for steps without a connection: the login name for the mailbox, usually your full email address. Leave blank when a connection is attached.
- **Password · Optional**: Only for steps without a connection: account password or app password. Prefer a connection: a password typed here is stored in the workflow definition.
- **Mailbox · Optional**: The folder the email is in. A UID only means something inside one folder. Default: INBOX.
- **Message UID · Optional**: The email's UID, normally mapped from a fetch or trigger step, such as {{steps.fetch_mail.emails[0].uid}}.
- **Target Folder · Optional**: The folder to move the email into. It must already exist on the server.
- **Use TLS · Optional**: Implicit TLS (port 993). Off = the connection starts unencrypted on port 143. On by default.
- **Upgrade with STARTTLS · Optional**: With Use TLS off, encrypt the port-143 connection with STARTTLS before sending the password. Turn this on for any real server on port 143. Otherwise the mailbox password crosses the network in the clear. Off by default.
- **Ignore TLS Cert Errors · Optional**: Accept self-signed / mismatched certificates. Off by default.

### Email (IMAP) › Delete Email

Flag one email as deleted and (by default) purge it from the folder.

- **IMAP Host · Optional**: Only for steps without a connection: the address of your email provider's incoming mail server, such as imap.gmail.com. Leave blank when a connection is attached.
- **Port · Optional**: Only for steps without a connection: 993 for implicit TLS, 143 for plain or STARTTLS. A connection's own port always wins. Default: 993.
- **Username · Optional**: Only for steps without a connection: the login name for the mailbox, usually your full email address. Leave blank when a connection is attached.
- **Password · Optional**: Only for steps without a connection: account password or app password. Prefer a connection: a password typed here is stored in the workflow definition.
- **Mailbox · Optional**: The folder the email is in. A UID only means something inside one folder. Default: INBOX.
- **Message UID · Optional**: The email's UID, normally mapped from a fetch or trigger step, such as {{steps.fetch_mail.emails[0].uid}}.
- **Permanently Delete · Optional**: On purges the email immediately. Off only flags it as deleted, so it disappears from mail clients but can still be recovered until the folder is purged. On a server without the UIDPLUS extension, purging also removes any other message already flagged as deleted in this folder. On by default.
- **Use TLS · Optional**: Implicit TLS (port 993). Off = the connection starts unencrypted on port 143. On by default.
- **Upgrade with STARTTLS · Optional**: With Use TLS off, encrypt the port-143 connection with STARTTLS before sending the password. Turn this on for any real server on port 143. Otherwise the mailbox password crosses the network in the clear. Off by default.
- **Ignore TLS Cert Errors · Optional**: Accept self-signed / mismatched certificates. Off by default.

Source: https://docs.gorunner.io/apps/email-imap