Forwarding
Forwarding
Forwarding reads a mailbox on a timer and sends each new email into one place, usually a Telegram group chat, so a team hears about mail where it already talks. It keeps a log of every email it picked up and can send each destination a daily report (module mailforward).
In the sidebar under Communications → Forwarding. Needs the Mail module: a route forwards a mailbox connected under Mail.
Forwarding
The screen has three tabs.
- Mailboxes: one row per route. Each shows the mailbox, where it Forwards to, the Bot it sends through, its Filters ("everything", or how many and whether all or any must match) and its Health: healthy, overdue, not yet read, failing (the error shows on hover) or paused, with when it was last read. Counts of routes forwarding, failing and paused sit above the list.
- What was forwarded: every email a route picked up, newest first, with the mailbox, its status (pending, sending, sent, failed, abandoned), how many tries it took and when it was received. A failed email shows when it will be tried again. Filter by status, or search by subject or sender, word by word. Sort by date, address, subject or status.
- Daily reports: one row per destination that gets a daily report, with the hour and timezone it is sent at, the bot, when it was last sent and whether it is on.
What you can do
Forward a mailbox
- Open Forwarding → Mailboxes and choose Forward a mailbox.
- Choose the Mailbox. You can route mailboxes you own, or ones shared with you at manage level.
- Choose the Destination. Destinations are the group chats and shared inboxes set up under Notifications.
- Choose the bot to Send through, or leave the default. A chat only hears from a bot that is a member of it.
- Set Check every (minutes), from 1 to 1440.
- Tick Include the email's text and Send attachments under it as you need, and leave Forwarding is on ticked.
- Save.
To point several mailboxes at the same destination at once, choose Map several instead.
Forward only some mail
- Choose Edit on a route.
- Under Filters, pick a field (from, subject or to), a comparison (contains, does not contain, is exactly, starts with, ends with) and a value, for example
example.com. - Add more filters if you need them and choose whether all match or any matches.
- Save. With no filters, every email is forwarded.
Read receipts from emails
A route has a switch, Read receipts from emails sent here. It is off by default. When it is on, receipts that arrive by email at that mailbox are read for the route's owner, and a receipt card with project buttons goes to their chat or dashboard. Nothing is saved until the owner says yes. A route with no owner cannot turn it on.
Pause, read now or delete
- Pause stops a route without losing it. Resume starts it again.
- Read now reads the mailbox at once instead of waiting for its next turn. It is unavailable for a paused route or a mailbox switched off in Mail, and the button says why.
- Delete stops the route and removes it.
Retry an email that did not arrive
- Open What was forwarded and filter by failed or abandoned.
- Read the error on the row.
- Once the cause is fixed, choose Retry. It sends the same email to the same destination.
A failed email is tried again on its own with growing waits between tries. After the fifth failed try it is marked abandoned and left for a person.
Send a destination a daily report
- Open Daily reports and add one.
- Choose the Destination, the Hour (0-23) and the Timezone the hour is read in, for example
Europe/London. - Choose the bot to Send through and tick Send it.
A daily report lists each email the destination was sent that day. It goes out on quiet days too, so silence means quiet, not broken. Each destination has at most one.
Use it from the chat
In a chat that a route forwards into, people with permission to see forwarding can type /check (read this chat's mailboxes now), /status (health and when each mailbox was last read), /accounts (the mailboxes forwarding here), /last (the last few emails, up to 10) and /today (every email forwarded here today). Replying in the chat to a forwarded email sends an email back to its sender, if you may send from that mailbox.
Who can do what
| Permission | Label | Lets you |
|---|---|---|
mailforward:read | See forwarding and what was forwarded | Open Forwarding, see routes, the log and daily reports, and use the chat commands. |
mailforward:manage | Route mailboxes into chats | Create, edit, pause, read now and delete routes for mailboxes you own or manage, retry emails, switch read receipts, and set up daily reports. |
Reading a mailbox also depends on Mail: a route reads the mailbox as the person who owns it. See People, roles and permissions.
What happens on its own
| Job | When | What it does |
|---|---|---|
poll | Every minute | Reads each route whose interval has come round, as the mailbox's owner, and forwards what is new and passes the filters. A route with nowhere to send is not read. |
retry | Every minute | Tries failed forwards again, oldest due first, up to 50 a minute, and marks an email abandoned after its fifth failure. |
digest | Every minute | Sends each daily report when its hour comes round in its own timezone. |
All three run every minute because each route and each report has its own interval or hour. A minute with nothing due does nothing.
Needs
Mail, for the mailboxes. A destination, set up under Notifications, and a bot from Comms to deliver into a chat.
What agents can do
An agent can explain why an email did or did not arrive: list routes, read one route and its filters, and search the log. It can retry a failed email, read a mailbox now, add or remove a filter, and switch read receipts. It cannot create, repoint or delete a route, because where a mailbox forwards is its owner's decision. By default reads go through, and the changes wait for a person to approve unless an approval rule says otherwise. Removing a filter lets more mail through, so it is treated as a removal. See Agents and approvals.
Read only: mailforward.routes, mailforward.recent, mailforward.route, mailforward.filters, mailforward.digests
Change, needs approval: mailforward.retry, mailforward.poll, mailforward.addFilter, mailforward.removeFilter, mailforward.setReadReceipts
mailforward.recentlists recently forwarded emails, optionally for one route, one status, or a search of subject and sender.mailforward.retrytakes a log entry's id, not a route's.mailforward.addFiltercan only narrow what already goes to a destination somebody chose.mailforward.setReadReceiptsswitches Read receipts from emails sent here on or off for a route.
Over MCP the same tools are named mailforward__routes, mailforward__retry and so on. See API keys and MCP access.