# Bring your team mail into IoTReady

> Set up a shared mailbox such as orders@ or support@ in your workspace, either by forwarding your existing address to it or by connecting it over IMAP and SMTP.

- **Page** - https://iotready.com/docs/platform/mail
- **Book** - [Platform](https://iotready.com/docs/platform.md)

A shared mailbox is a team address - `orders@`, `support@`, `recruiting@` - whose
mail lives in your workspace. Staff read it, assign it, tag it, answer it and
link a thread to any record, like the order it's about, all in the portal.

There are two ways to get your mail in. Pick one per mailbox.

|                   | Auto-forwarding                                        | IMAP and SMTP                                      |
| ----------------- | ------------------------------------------------------ | -------------------------------------------------- |
| Setup             | Add a forwarding rule to your existing address         | Give the workspace your mail server and a password |
| Replies go out as | The workspace address, like `orders+acme@iotready.app` | Your own address, like `orders@yourcompany.com`    |
| You hand over     | Nothing but a copy of incoming mail                    | A mailbox password                                 |
| Arrives           | About a minute after it's sent                         | Within the polling interval, a minute by default   |

If you can live with replies coming from the workspace address, forwarding is
the lighter option. If customers must see your own address, use IMAP and SMTP.

An administrator sets either one up under **Mailboxes** in the admin area of your
workspace.

## Auto-forwarding

Your workspace gets an address of its own for each mailbox, in the form
`<name>+<workspace>@iotready.app`. For a workspace called `acme` and a mailbox
called `orders`, that's `orders+acme@iotready.app`. You keep your own address and
forward it there.

1. As an administrator, create a mailbox in your workspace and choose the hosted
   transport. Give it a name, such as `orders`. The workspace shows you its
   address.
2. In your mail provider, add a forwarding rule from your own address to that
   address. Keep a copy in the original mailbox if you want a safety net.
3. If your provider asks you to confirm the forwarding address, it sends a
   confirmation to the new mailbox. Open the mailbox's page in the admin area:
   the confirmation code and link show there for 14 days. Gmail works this way.
4. Send a test message to your own address. It shows up in the mailbox.

Replies from the workspace go out as the hosted address, and customers who reply
to them land back in the same thread. Delivery shows on the thread: "Delivered",
or "Not Delivered" with the reason.

> **Forward only the mail you want**
>
> A forwarding rule copies what you tell it to. If the address you forward is a
> personal one, forward only the messages to the team address, not everything.

## IMAP and SMTP

Use this when replies must go out from your own address, or when you'd rather the
workspace read the mailbox directly. It works with any provider that offers IMAP
and SMTP: Fastmail, Zoho Mail, a server you run yourself, or Gmail with an app
password.

You need:

- the IMAP and SMTP server names, like `imap.example.com` and `smtp.example.com`
- the user name, usually the full address
- a password for the mailbox. Use an app password if your provider has them, not
  the password the person signs in with.

Then:

1. As an administrator, open **Mailboxes** and create one with the IMAP + SMTP
   transport. Enter the two server names, the user name and the address.
2. Enter the password. The workspace keeps it encrypted and never shows it again.
3. Press **Test**. It connects, signs in and opens the folder without reading any
   mail, and tells you which step failed if one does.
4. Set how many days back the first read should go (**Backfill days**; 0 means
   from the beginning of the mailbox) and save. That older mail comes in first,
   then new mail as it arrives.

Connections are encrypted. Ports are 993 and 465 unless you pick STARTTLS. If you
leave out the SMTP server the mailbox receives mail but can't send.

Two options help when the mailbox isn't a clean one:

- **Folder** names the folder or label to read, so a filter at your provider can
  fill it with just the mail you want. The default is the inbox.
- **Recipient filter** keeps only mail addressed to the addresses you list, for
  a personal mailbox that also receives the team address.

The workspace never marks anything read on your server.

## Who can see a mailbox

Not everyone in your workspace. Access comes from roles: an app's role can give
read or write access to a mailbox, and administrators always have it. Give the
team that role and they see the mailbox in **Mail** in the portal.

## Help

Write to <support@iotready.com>.