Connection Modes
How an inbox authenticates, and how mail reaches Ticku. Set per inbox — one tenant can run different modes on different mailboxes.
Connection mode is orthogonal to the mail provider. Gmail over IMAP is provider gmail with mode imap_basic; Microsoft 365 can run in any of the three.
At a glance
graph_app | imap_oauth | imap_basic | |
|---|---|---|---|
| Called in the UI | Microsoft Graph (app-only) | Sign in with Microsoft | IMAP / SMTP |
| Delivery | Push — arrives in seconds | Polled | Polled |
| Authenticates with | Client credentials against the tenant's Entra directory | Delegated refresh token from a per-mailbox sign-in | Stored username + password |
| Consent needed | One tenant-wide Global Admin consent | The mailbox owner signs in — no Global Admin | None |
| Access granted | Every mailbox in the directory | Only the one mailbox signed in | Only that account |
| Works with Microsoft 365 | Yes | Yes | No — see below |
| Secret stored by Ticku | None (uses the platform app registration) | Refresh token, encrypted | Password, encrypted |
All stored credentials are encrypted at rest with EMAIL_ENCRYPTION_KEY (AES-256-GCM).
graph_app — Microsoft Graph, app-only
The only push mode. Microsoft Graph holds a subscription against the mailbox and calls Ticku when mail arrives, so a ticket appears within seconds rather than on the next poll.
Ticku authenticates with the same multi-tenant app registration used for web SSO (ENTRA_CLIENT_ID), against the directory recorded in the tenant's entraDirectoryId. There are no per-tenant credentials to collect — an earlier version asked each tenant for its own Azure app registration, client id, and secret, and that has been removed. The real precondition is now simply "this tenant has a registered Entra directory".
Setup: Admin → Email → connect, which sends a Global Admin through the tenant-wide consent screen once. After consent, any mailbox in that directory can be used.
:::caution Requires Mail permissions on the platform app
This mode needs Mail.ReadWrite and Mail.Send application permissions, with admin consent, on the SSO app registration. Without them every mail call returns 403. Confirm this before choosing app-only mode — see Azure App Registration.
:::
Subscriptions expire and are renewed automatically by the email cycle; the inbox card shows the current expiry.
imap_oauth — Sign in with Microsoft
A delegated connection to one specific mailbox, in the style of Freshdesk or Zendesk. An admin enters the support address, clicks Sign in with Microsoft, and authenticates as that mailbox. Ticku keeps the resulting refresh token — the only long-lived secret — and mints short-lived access tokens on demand, using them as XOAUTH2 credentials for IMAP and SMTP.
Pick this when you can't get Global Admin consent, or when granting an application directory-wide mailbox access is more than you want to give up for one support address.
Mail is polled, not pushed — see the email cycle for the interval.
:::tip Sign in as the mailbox, not as yourself The sign-in chooser is pre-filled with the address you typed, but an admin can still authenticate as a different account. Ticku records the account that actually signed in separately from the mailbox address, so a mismatch is visible on the inbox rather than surfacing much later as a confusing failure. :::
Disconnecting clears the token and disables the inbox — an enabled inbox with no credentials would just fail in a loop until the circuit tripped, which reads as a bug rather than a choice.
imap_basic — IMAP / SMTP with a password
Plain IMAP and SMTP with a stored username and password. Host, port, TLS, and folder are all configurable on each side.
:::danger Does not work with Microsoft 365
Basic authentication for IMAP, and SMTP AUTH, are retired in Exchange Online. This mode exists for Gmail app passwords, Zoho, and on-premises mail hosts. Against Microsoft 365 it will fail to authenticate — use imap_oauth instead.
:::
Saving basic credentials switches the inbox to this mode and clears any delegated refresh token, so a connection you believe you replaced can't be silently revived later.
Testing a connection
Test connection on the inbox exercises whatever the inbox is actually configured to use — Graph for app-only mode, a real IMAP handshake otherwise. A pass therefore means the path that will run in production works, not that a parallel approximation of it does.
For polled modes, Poll now fetches immediately instead of waiting for the next cycle. It's a no-op in push mode, where the webhook has already delivered.