Email (IMAP)
Included with Macro DeckSee unread emails and the newest messages of any IMAP inbox on your deck, and react when mail arrives.
Email Inbox widgets with a list of the latest messages, the unread messages and the unread count
- Works with Gmail, iCloud Mail, GMX and any IMAP server
- Unread count or message list on an Email Inbox widget
- Triggers when an email arrives or is read
- Variables for unread count, latest sender and subject
- Read-only: never changes, moves or deletes an email
The Email (IMAP) integration reads one folder of an email account, usually the inbox, from any provider that offers IMAP, such as Gmail, iCloud Mail or the mail of your own domain. Macro Deck only reads. It never changes, moves or deletes an email, and never marks one as read.
For Gmail, iCloud Mail, Yahoo Mail, AOL Mail, Fastmail, Zoho Mail, GMX, WEB.DE, T-Online, IONOS, mailbox.org and Posteo, you pick the provider and Macro Deck fills in the server settings. For any other service, pick Custom server and enter the IMAP settings from your provider's help pages. The connection is always encrypted, with SSL/TLS or STARTTLS, and the server's certificate is always checked.
What you can do with it
- Email Inbox widget: shows the number of unread emails, or a list of the newest emails with sender, subject and time.
- Triggers: Email Received, Unread Count Changed, Email Read or Unread, Inbox Disconnected and Inbox Connected run actions in an automation or on a widget. Email Received can be limited to a sender or a subject.
- Variables: the unread emails of every inbox together, and for each inbox its unread and total emails, the sender and subject of its newest email and whether it is connected.
Some example setups:
- An Email Inbox widget on your deck that shows how many unread emails wait in your work inbox.
- An automation on Email Received from your manager that shows a notification.
- An automation on Inbox Disconnected that shows a notification when your mail server cannot be reached.
How it behaves
Macro Deck keeps a connection open and hears about new mail within seconds when the server supports it, and checks every minute when it does not. Email Received does not run for emails that were already there when Macro Deck starts, so a restart does not replay your inbox. When an inbox cannot be reached, the widget keeps its last emails and shows a warning, and Macro Deck keeps trying to reconnect.
You can add as many accounts as you like, and several folders of the same account, each as its own configuration. Each inbox's variables are named after its configuration name, for example email_work_unread_count for an inbox called Work.
Everything the widget shows, including senders, subjects and previews, can be seen on every device connected to your Macro Deck.
What you need
- Macro Deck 3 on Windows, macOS or Linux
- An email account with IMAP access turned on
- Your password, or an app password if the account uses two-step verification
- For a custom server: the IMAP server name, port and security setting
Set it up
Step 1: Create an app password if needed
Most providers refuse your normal password from other apps once two-step verification is on. Create an app password in your account's security settings, for example under App passwords in your Google account for Gmail, or at account.apple.com under Sign-In and Security for iCloud Mail.
Step 2: Open the Email (IMAP) setup
In the sidebar, click Integrations and then Email (IMAP). Click Add configuration under Configuration on the Overview tab. Turning on the switch at the top right opens the same dialog, and the integration is turned on once the setup is done. The Connect an email account dialog opens.
Step 3: Fill in the account
Enter:
- Configuration name: the inbox's name in Macro Deck, such as
Work. Its variables are named after it. - Email provider: your email service, or Custom server. For a custom server, also fill in IMAP server, Port (
993for SSL/TLS, usually143for STARTTLS) and Security. - Username: usually your full email address.
- Password: your password or the app password. It is stored encrypted on this computer.
- Folder: the folder to watch,
INBOXby default.
Click Continue. Macro Deck signs in once to check the settings and says what went wrong if it cannot.
- Configuration name: the inbox's name in Macro Deck, such as
Step 4: Add an Email Inbox widget
On the Deck page, add an Email Inbox widget. In its settings, choose the Inboxes to show and what to Show: Unread count or Message list. Leave Inboxes empty to show every connected inbox.
Step 5: Add a refresh button
On the Deck page, make sure the deck is unlocked (the button at the top right reads Lock) and click a button. The editor opens with Short Press selected. Click + Add action, choose Email on the left of the Add action dialog and pick Refresh Email Inboxes. Click Save. Pressing the button checks every connected inbox right away.
Step 6: React to new mail
In the editor of a button or an automation, click + Add event trigger and pick Email Received. Limit it to an Inbox, a Sender or a Subject if you like, then click + Add action and pick what should happen, such as a notification.
Actions1
Put these on a button or run them from a flow.
- Refresh Email Inboxes
- Checks every connected inbox for new messages right away instead of waiting for the next update.
Triggers5
A button or flow can react to these events.
- Email Received
- Runs when a new email arrives in an inbox. Can be limited to an inbox, a sender and a subject.
- Unread Count Changed
- Runs when the number of unread emails in an inbox changes.
- Email Read or Unread
- Runs when an email is marked as read or unread, for example in your mail app.
- Inbox Disconnected
- Runs when an inbox loses its connection to the mail server.
- Inbox Connected
- Runs when an inbox is connected again after it was disconnected.
Variables5
Show these values on buttons and widgets, or use them in conditions.
email_unread_count- The unread emails of every inbox together.
email_inbox_count- The number of connected inboxes.
email_<inbox>_unread_count,email_<inbox>_total_count- The unread and all emails in an inbox, such as
email_work_unread_countandemail_work_total_count. email_<inbox>_latest_sender,email_<inbox>_latest_subject,email_<inbox>_latest_received_at- The sender, subject and time of the newest email in an inbox.
email_<inbox>_is_connected- Whether the inbox is connected.
Widgets1
Add these to your deck from the widget picker.
- Email Inbox
- Shows how many unread emails are waiting, or the newest emails of your connected inboxes.
Frequently asked questions
Does Macro Deck mark emails as read?
No. Macro Deck only reads. It never marks an email as read, and never changes, moves or deletes one.
Why does the server refuse my password?
Most providers, Gmail and iCloud Mail among them, refuse your normal password from other apps when two-step verification is on. Create an app password in your account's security settings and enter it as the Password. Also check that the Username is your full email address.
Can I connect Outlook.com or Microsoft 365 mail?
Microsoft lets most of these accounts sign in to IMAP only with OAuth, which Macro Deck does not support yet. If your account still offers app passwords, pick Custom server and use one.
Can I connect several accounts or folders?
Yes. Click Add configuration on the Email (IMAP) page for each account, or for another folder of the same account. A folder that is already connected is refused.
What happens when I change my email password?
Integrations shows Email sign-in failed for the account, and its widgets show Offline. Choose Edit connection next to the account and enter the current password or a new app password. The inbox keeps its name, so widgets, triggers and variables keep working.
Where is my password stored?
The password is stored encrypted on the computer that runs Macro Deck and is only used to sign in to your mail server.
More in Calendar and email
Google Calendar
Included with Macro DeckShow your Google Calendar events on your deck, count down to the next meeting and join it with one press.
Outlook Calendar
Included with Macro DeckShow your Outlook and Microsoft 365 calendar on your deck and join Teams meetings with one press.