Email inboxes

An email inbox answers one mailbox. Kommio reads new mail over IMAP without moving, deleting or marking anything in the mailbox, threads it into conversations, recognises bounces and auto-replies, and sends your agents' replies over SMTP from the same address. A mailbox connects in one of two ways:

• Sign in with Microsoft 365 or Google (OAuth 2.0). No mailbox password is stored: Kommio keeps the sign-in, encrypted, and uses it for IMAP and SMTP. This is the way into Exchange Online now that Microsoft has switched basic authentication off, and the recommended way for Google Workspace and Gmail.
• IMAP and SMTP with a password (or an app password), for any other provider.

Settings › Inboxes › Add inbox › Email offers both. Settings › Marketplace also lists Microsoft 365 email and Google email; installing one opens the same step with the provider chosen, and the inbox then appears under Marketplace › Installed with the signed-in account and the last renewal.

How mail is read, and the copy of every email

• Push and poll. For a mailbox whose server offers IMAP IDLE, Kommio holds one connection that tells it when new mail arrives, so a new email reaches your agents within seconds. While that connection is live, the mailbox is also synced every ten minutes as a safety net; a mailbox without IDLE, or whose connection is down, is polled every minute.
• What the inbox shows. Settings › Inboxes says which it is under the inbox's status: "Live (IDLE), last change 3 min ago", "Live (IDLE), synced 7 min ago" while no change was reported yet, "Polling every minute (no push), synced 1 min ago", or "Polling every minute (push connection down)". A mailbox is "Sync is late" when it is polled every minute and the last sync is older than ten minutes, or, with a live connection, when neither a sync nor a change arrived within twenty minutes. GET /inboxes/{id} carries the same under watch.
• The copy as it arrived. Every inbound email is also kept exactly as it arrived, for a dispute, a forensic question or a second look after a parser fix, including an email that was set aside as malformed. The conversation shows the parsed message and its files; the copy is kept apart. Outbound mail is not copied, nor is history imported from Chatwoot.
• How long. Settings › Privacy, "Raw email", keeps the copies for 90 days by default (0 keeps them; at most 3,650 days); expired copies are deleted every night, and erasing a contact deletes the copies of their messages at once. They count as their own category, "Raw email copies", in the workspace's storage.
• Downloading one. A person with inboxes:manage downloads a copy as an .eml file through the API, and only when they could read everything in it: the conversation is within their visibility, they see email addresses in clear (the email carries the customer's address), and no file on the message is marked as a kind of personal data they do not see in clear. Otherwise the download is refused with 403; a message without a copy answers 404. Every download is in the audit log. A download button in the thread follows.

curl -o 90211.eml "$KOMMIO_URL/conversations/4410/messages/90211/raw" -H "Authorization: Bearer $KOMMIO_KEY"

Sign in with Microsoft 365 or Google

1. Sign in

   Choose Microsoft 365 or Google Workspace, then Sign in with Microsoft (or Google). Sign in with the account that owns the mailbox, or, on Microsoft 365, an account that has access to the shared mailbox. Starting a sign-in needs the inboxes:manage permission.

2. Choose the mailbox

   Back in Kommio, the step shows the account you signed in with. Leave the mailbox address empty to use that account's own mailbox, or type another one, such as a shared mailbox. Name the inbox.

3. Pick the agents and test

   Choose who works the inbox and send a test email.

The mail servers of a signed-in inbox come from the provider and cannot be changed, so the sign-in is only ever sent to Microsoft's or Google's own servers:

Kommio asks Microsoft for IMAP.AccessAsUser.All, SMTP.Send, offline_access, openid and email, and Google for https://mail.google.com/, openid and email. A sign-in that did not grant mailbox access (Google lets people untick it) is refused with that reason.

What the mailbox needs

Most refusals come from a mailbox setting rather than from the sign-in. On Microsoft 365, IMAP and authenticated SMTP must be allowed for the mailboxes involved (the Microsoft 365 admin center › Users › Active users › the user › Mail › Manage email apps, or Exchange Online PowerShell):

Set-CASMailbox -Identity [email protected] -SmtpClientAuthenticationDisabled $false -ImapEnabled $true
Set-CASMailbox -Identity [email protected] -ImapEnabled $true

That covers the signed-in account's own mailbox for SMTP and the mailbox Kommio reads for IMAP. Security defaults and "block legacy authentication" policies do not block it: signing in with OAuth is modern authentication. If your tenant does not let people consent to apps themselves, an administrator grants consent once. On Google Workspace, IMAP must be allowed under Apps › Google Workspace › Gmail › End user access, and if third-party app access is restricted, the app has to be trusted.

Shared mailboxes on Microsoft 365

A shared mailbox such as support@ has no password of its own. Instead a person, or a dedicated licensed account, with Full Access to it signs in, and the inbox's mailbox address is the shared mailbox's:

• Kommio reads the shared mailbox with the signed-in account's sign-in.
• Replies go out from the shared mailbox's address, which Exchange accepts only when the signed-in account also has Send As on it; without it, a reply fails with "SendAsDenied" and the message shows as failed.

Add-MailboxPermission -Identity [email protected] -User [email protected] -AccessRights FullAccess -InheritanceType All
Add-RecipientPermission -Identity [email protected] -Trustee [email protected] -AccessRights SendAs -Confirm:$false

The same account can serve several shared mailboxes; connect each as its own inbox, and each keeps its own sign-in. Google has no shared mailboxes over IMAP: a Google inbox's address may only differ from the account when it is one of that account's "Send mail as" addresses.

When a sign-in stops working

Kommio renews the sign-in on its own, also for paused inboxes. When the provider refuses to renew it (the person revoked Kommio's access, their password changed, an administrator ended their sessions), Kommio stops asking, puts every inbox that uses the sign-in in error, and tells everyone who manages inboxes, in the app and by email, once. The inbox's page then opens with a banner that says what to do, and Settings › Inboxes shows How to fix it linking to this page. No mail is lost: new mail is read as soon as someone signs in again. On the inbox's page, the Mailbox sign-in card shows who is signed in and offers Reauthorise, which can also switch to another account.

The same card on a password inbox offers Connect with Microsoft or Connect with Google: the inbox keeps its address, history and place in the mailbox, and its stored passwords are deleted. An email inbox imported from Chatwoot that used Microsoft or Google sign-in arrives paused and waiting for that sign-in.

Security

• The sign-in uses the authorization-code flow with PKCE. The request is signed, expires after ten minutes and is tied to the browser session of the person who started it; a callback from another browser, session or workspace is refused before anything is exchanged.
• Tokens are encrypted per workspace and never returned by the API, written to the audit log, events or logs. The API shows the signed-in account, the scopes and the state only.
• Every call to the provider goes through Kommio's outbound client, like IMAP and SMTP.
• A sign-in that no inbox ended up using is deleted after 24 hours.