Connecting a mailbox

A mailbox is a shared inbox — support@yourcompany.com, say — that Held Open fetches mail into and sends replies from. Setting one up is a workspace-admin task, done in two steps: create the mailbox, then connect it.

1. Create the mailbox

Go to Settings → Mailboxes → New mailbox. The dialog only asks for a Name (e.g. “Support”) and an Email address (e.g. support@example.com) — creating the mailbox doesn’t collect IMAP/SMTP yet, those come next. You’ll be dropped straight into the new mailbox’s settings.

Until it’s connected, the mailbox list shows it tagged “No IMAP configured.”

2. Connect it

On the mailbox’s settings page, open the Connection tab. There are two independent halves — receiving and sending — plus an OAuth card that only appears if you choose OAuth for either one.

Receiving (IMAP)

How Held Open fetches mail into this mailbox.

Server

Port

Encryption

Authentication

Username

Password

Server / Port — your provider’s IMAP host (default port 993).
Encryption — None, SSL, TLS, or STARTTLS (SSL is the default).
Authentication — Password, or OAuth 2.0 (XOAUTH2) for Gmail and Microsoft 365 (see below).
Username / Password — hidden entirely if you chose OAuth.
Folders to fetch — defaults to INBOX.
Sent folder — optional, if you also want Held Open reading a provider-side Sent folder.
After fetching a message — Leave it, Mark read, Move, or Delete; Move needs a folder name.
Validate TLS certificate — checked by default.

Test IMAP connects using whatever’s currently in the form — including unsaved changes — and lists the folders it finds. Save connection settings is separate: testing doesn’t save, and saving doesn’t test. Do both.

Sending (SMTP)

Same shape: Server, Port (default 587), Encryption (None, SSL, or TLS — TLS is the default), Authentication, and Username/Password if not using OAuth. Test SMTP sends a real test email, prefilled to your own address.

Connecting via OAuth (Gmail or Microsoft 365)

If you set either side’s Authentication to OAuth, an OAuth connection card appears: pick the Provider (“Gmail / Google Workspace” or “Microsoft 365 / Outlook” — these are the only two), enter your Client ID and Client secret, then click Connect. That opens the provider’s consent screen in the same tab; approving it brings you back connected. Disconnect is available once connected.

Picking a provider here also fills in that provider’s known server/port defaults for you.

Things worth knowing before you fill this in

Passwords are write-only. Leaving a password field blank on save keeps whatever’s already stored — it doesn’t clear it.
Ports aren’t range-checked. Neither the form nor the server validates that a port number is sensible, only that it’s set.
You need the mailbox’s Owner grant to see or change credentials — being a workspace admin isn’t automatically enough if someone scoped your mailbox access down. See mailbox access and teammates.

Auto-reply

On the mailbox’s Auto-reply tab: an enable switch, a Subject, and a Message. Both fields are disabled until you turn the switch on. It’s sent once, to the customer, when they open a new conversation — never on a reply, and never as a response to a bounce or another auto-responder.

Signature

The General tab has a Signature field — plain text, one per mailbox, not per agent. It saves along with everything else on that tab, not as its own separate action. This is one of the only two places in Held Open where placeholder substitution in a message body actually works (the other being auto-reply, above) — saved replies don’t do this, despite what their own editor claims; see Replying and notes.

Custom fields

The Custom fields tab defines per-conversation fields — despite showing up in what looks like the customer sidebar, a value you fill in belongs to the conversation, not the customer record. Defining one needs workspace-admin access; filling in its value on a conversation doesn’t.

Five types: Text, Number, Date, Dropdown, and Multiselect. Dropdown and Multiselect need at least one option before you can save — enter them one per line. Every field also has a Required checkbox.

Turning a forwarded email into a ticket

A mailbox can also accept forwarded email as a way to open a new ticket, independent of IMAP/SMTP. On the mailbox’s General tab, the Forward-to-ticket address field sets an address agents can forward mail to — anything sent there becomes a new conversation attributed to the original sender, not the forwarding agent. Leave it blank to disable; every mailbox also always accepts this at its own address with a +forward tag added (e.g. support+forward@yourcompany.com), whether or not a custom address is configured.

Held Open recovers the original sender either from an attached/embedded original message (how Apple Mail and most “forward as attachment” clients send it) or from the inline “From:”/“Subject:” header block Gmail and Outlook paste above the quoted text — whichever is present. If neither is found, the ticket is still created, just without a customer attached yet; an internal note says so, and the customer can be set by hand from there.

Only mail from a recognized agent triggers this. A forward from anyone else becomes an ordinary new ticket from whoever actually sent it, not from the forwarded content.

Tagging an agent to assign the ticket

Writing @FirstName (or @FirstName LastName, if two teammates share a first name) anywhere in your own note above the forwarded content — not inside the quoted original — assigns the new ticket to that agent automatically, as long as they have access to the mailbox. If the tag doesn’t resolve to exactly one such agent, the ticket is left unassigned and the internal note explains why (no match, more than one match, or the tagged agent lacks access to the mailbox) instead of failing silently.