Email (IMAP)
Read, search and manage email in an IMAP mailbox.
Connect Email (IMAP)
- In the sidebar, open Connections and press Add connection.
- Type
imapand choose Email (IMAP). - Fill in the fields. Each one says Required or Optional.
- 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 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 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.
Do things in Email (IMAP)
Add an Email (IMAP) step and choose what it does. Choose a row to see its fields.
- Fetch EmailsConnect to an IMAP server and fetch recent or matching emails from a mailbox.
- Mark Email as Read/UnreadSet or clear the read (\Seen) flag on one email.
- Move EmailMove one email to another folder: the usual way to file mail once a workflow has processed it.
- Delete EmailFlag 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.
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.
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 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.
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.