Support mailboxes
Overview
Support mailboxes are the mail accounts tickets arise from — typically the address customers write to. Two types are available: Gmail / Google Workspace and IMAP / SMTP (generic).
A boundary that saves time in daily use: these mailboxes are support's ticket intake and reply route. The system mail accounts are something else — the system sends invitations, documents and notifications through those. Tickets deliberately use their own mailboxes so that replies land in the right thread.
Core tasks
Create a mailbox. New mailbox requires type, label and connection details. With Gmail, access runs through a previously configured integration; with IMAP/SMTP you enter the server details directly.
Keep an eye on the state. The list shows label, type, connection and status — active or inactive. The note no password is a finding worth taking seriously: a mailbox without credentials fetches nothing but reports no error either, because it never attempted to connect.
Fetch now. Active mailboxes are fetched every two minutes. Fetch now in the header fetches new mail from all active mailboxes immediately — the same path as the schedule, via Gmail and IMAP. The message states how many new mails were queued; they become tickets in the background, and the connection state in the list is up to date afterwards. The button appears with the permission tickets.config.manage; via the API the action is POST /v1/tickets/mail-poll-run.
Set up Gmail push. Instead of waiting for the schedule, Gmail can report new mail immediately. This needs a Pub/Sub topic in your Google Cloud project that Gmail may publish to (role Pub/Sub Publisher for gmail-api-push@system.gserviceaccount.com). The steps:
- In the mailbox (type Gmail) enter the Pub/Sub topic, e.g.
projects/my-project/topics/gmail-support, and save.
- The mailbox row now shows the push address. Create a push subscription on the topic in Google
Cloud and enter exactly this address as its endpoint — it contains a secret, only deliveries to this address trigger anything.
- Register push (bell in the row) registers the mailbox with Gmail. The row then shows *Push active
until …*.
Gmail ends a registration after seven days at most; the system renews it itself every twelve hours. If Gmail rejects it (for example because the topic is missing or Gmail may not publish to it), the row shows Push failing with the message. Fetching every two minutes continues in any case — push only speeds things up, it replaces nothing. Clear the topic to switch push off: deliveries to the old address are discarded.
Run several mailboxes. Separate addresses per brand or per area are the normal case, and the simplest way to establish ownership without a rule set.
Fields in detail
The What it does column answers what changes in the system — not what the field is called. The grey name behind the label is the API field: the same thing runs under that name through automation, import and AI tools.
The difference from your own mailbox: this is a support mailbox. What arrives becomes a ticket — not a message in your personal history.
Setting up a support mailbox
| Field | Required | Values / format | What it does |
|---|---|---|---|
Type type | yes | Gmail or IMAP | Decides the rest of the mask. With Gmail the provider grants access through the prepared connection; with IMAP you enter servers, ports and credentials yourself. |
Label label | yes | text | The name the mailbox appears under in the list. |
Email address email | yes | email address | The support address. It stands as the sender under every reply and is the target the customer writes back to. |
Connection integrationId | with Gmail | a prepared connection | Which login is used for access. |
IMAP server / port / encryption imapHost, imapPort, imapEncryption | with IMAP | address, number, SSL/TLS/none | Where mail is fetched from. No encryption sends credentials in the clear and is only defensible inside your own network. |
IMAP user imapUsername | with IMAP | text | Login name for fetching. |
Folder imapFolder | no | text | Which folder is read. Empty means inbox. |
SMTP server / port / encryption smtpHost, smtpPort, smtpEncryption | with IMAP | address, number, SSL/TLS/none | What is sent through. Kept apart from fetching because many houses use different servers for in and out. |
SMTP user smtpUsername | no | text | Login name for sending. Empty means the same as for fetching. |
Password password | with IMAP | text | The password. Stored encrypted and never shown again; entering it anew replaces it. For accounts with two-factor login an app password belongs here. |
Brand brandId | no | one of your brands | Which brand the resulting tickets run under — determines signature, templates and visibility. |
Active active | no | yes/no | Off stops the fetch without losing the setup. |
Pub/Sub topic (push) pushTopic | no, Gmail only | projects/<project>/topics/<topic> | Gmail reports new mail immediately via this topic instead of it arriving at the next fetch. Empty switches push off. Registration via Register push (POST /v1/support-mailboxes/{ulid}/gmail-watch). |
Push address pushEndpointPath | — | path, read-only | Endpoint of the Pub/Sub push subscription. Contains a secret — do not share. |
Push active until pushWatchExpiresAt / push error pushLastError | — | timestamp / text, read-only | How long the Gmail registration is valid and why the last one failed. |
Fetch history backfill | no | yes/no | Fetch older messages on the first run and turn them into tickets. Switch on with care: a grown mailbox otherwise produces hundreds of tickets at once. |
From date importFrom | no | date | Limits the backfill. The usual way to take the recent past along without waking the archaeology of 2019. |
Settings & permissions
- Module
module.tickets. - Permission
tickets.config.manage. - What becomes of the mail is decided by the mail rules in
Ticket settings — including assignment to a support team.
- Unclear arrivals land in the inbox rather than being guessed at.
- The blacklist applies before a ticket is created and keeps advertising out.
FAQ & troubleshooting
No tickets are arriving. Check in this order: is the mailbox active? Are the credentials right — does it say no password? With Gmail: is the underlying integration still valid?
Customer replies create new tickets. Then the case number is missing from the outgoing mail. Check the reply template under Communication.
Push is registered, yet mail only arrives after two minutes. Then the Pub/Sub delivery is not reaching the system. Check that the push subscription carries exactly the push address from the row and that your instance is reachable from the internet.
A mailbox suddenly fetches nothing. Usually the credentials have expired or were changed at the provider.
Should we enter the general sending account here? No. That belongs under System mail accounts. Only support mailboxes live here.