Email accounts

When you connect an email account, its mailbox joins the unified inbox of CommSync. Inbound messages arrive in real time over IMAP IDLE. Every email from a contact sits in the same conversation as their SMS messages.

How you connect depends on your mail provider. A Microsoft mailbox connects with Sign in with Microsoft: you sign in on the page of Microsoft, and CommSync never sees your password. Other providers connect with an app password.

Enter your address

Go to Settings → Email accounts and click Add email account. New accounts see the same screen in the guided setup at /onboarding.

Type your email address and click Continue. CommSync picks the right way to connect it:

• A personal address opens its card at once: Outlook.com, Hotmail, Live, Gmail, iCloud, Yahoo, or Fastmail.
• CommSync knows these domains in every country, for example hotmail.co.uk.
• A company address on Microsoft 365 opens Microsoft.
• A company address on Google Workspace opens Gmail.
• CommSync reads the public mail (MX) records of a company domain to decide.
• Any other address opens Other, with the address filled in.

To choose a card yourself, click Pick my provider instead. Each card starts the connect method of its provider:

Sign in with Microsoft

Microsoft turned off password sign-in over IMAP for Outlook.com and for Microsoft 365. An app password does not work for a Microsoft mailbox any more. So the Microsoft card has one button: Sign in with Microsoft.

The sign-in must finish in 10 minutes. After that, start again.

What CommSync asks Microsoft for

Work accounts: approval from IT

Most Microsoft 365 work accounts need a one-time approval from IT. Microsoft does not let a user approve IMAP access alone for most apps. When your organization needs this approval, CommSync shows a screen that says so. It offers three actions:

• Copy approval link. Send the link to your IT admin. The link is for your organization only.
• Send these instructions to someone else. CommSync emails the approval link and the steps to your IT admin.
• I am the admin. Open the approval page yourself, if you are the admin.

To send the instructions, type the email address of your IT admin. You can add a note. The email also shows your name. You can send at most 3 of these emails a day.

Microsoft can also show its own Need admin approval page with a request form. If you send that request, CommSync tells you that the request is with your IT team. After your admin approves CommSync, click Try again.

Send your IT admin the Microsoft 365 admin guide. It says what CommSync asks for, how to approve it, and how to remove it.

Personal accounts: turn on IMAP

Outlook.com turns IMAP off by default, and CommSync cannot read the mailbox until it is on. For an Outlook.com address, the screen before the sign-in shows the step first, with a button that opens the setting. On a computer, the setting opens in a window next to the CommSync window. On a phone, it opens in a new tab. When you come back, the screen says Welcome back, and you continue to the sign-in.

If IMAP is still off after you sign in, you do not sign in again. CommSync waits on a screen that says so, and checks the mailbox every 10 seconds. Turn IMAP on in another tab, then come back. The steps are in Turn on IMAP in Outlook.com.

Outlook.com sometimes refuses a good sign-in, so CommSync tries again by itself. A Microsoft account can have more than one address. For example, an account can sign in with a Gmail address and hold an Outlook.com mailbox. CommSync then tries each address of the account.

When the sign-in fails

When you sign in with a mailbox that your workspace already has, CommSync puts the sign-in on that line in two cases only. A line with an app password on the Microsoft servers switches to Sign in with Microsoft. A line that you connected with your own sign-in gets the new sign-in.

In every other case, CommSync stops, and nothing changes. CommSync does not send a Microsoft sign-in to mail servers that Microsoft does not own. It also does not replace the sign-in of a teammate. CommSync does not keep the sign-in that you just made.

Sign in with Google

Sign in with Google comes to workspaces in stages. Until it reaches your workspace, a Gmail mailbox connects with an app password (see below). The Gmail card works the same way it does today.

When Sign in with Google is on for your workspace, the Gmail card starts Sign in with Google. You do not type a server name, a port, or a password. One Google sign-in lets CommSync read the mailbox and send your mail.

CommSync shows a link to the app-password path, Use an app password instead, only when the sign-in cannot work for you. That is after two failed sign-ins in 24 hours, or at once when Google blocks the sign-in by policy. The Gmail sign-in guide covers the causes, and what a Google Workspace admin can do.

A Gmail mailbox that you connected with an app password continues to work. When Sign in with Google is on for your workspace, the account shows Switch to Sign in with Google.

Connect with an app password

iCloud, Yahoo, Fastmail, and Gmail (until Sign in with Google reaches your workspace) connect with an app password. An app password is a separate password that your provider makes for one app. Your main account password does not work for these providers.

Nobody has an app password in hand, so CommSync sends you to get one. The guide of your provider ends in one button, for example Open Google and make the password. On a computer, the button opens the provider's page in a window next to the CommSync window. The CommSync window moves aside to make room. The three steps stay in view next to the password field. On a phone, the page opens in a new tab.

Make the password on the provider's page, copy it, and come back. CommSync sees the return, says Welcome back, and puts the cursor in the password field. Press Paste the app password to paste from the clipboard, or paste with the keyboard. A green line under the field says when the password has the right shape. Then press the Connect email button.

If you already have an app password, press I already have one on the guide instead. The link next to the password field opens the provider's page at any time.

CommSync fills in the server settings and the username, and keeps them under Server settings.

CommSync checks the shape of the password before it sends anything. When the password does not look like an app password, CommSync says so. It links the page that makes one. If you are sure, click It is an app password. Connect.

CommSync also stops you when the address belongs to another card, for example an Outlook.com address in the Gmail form. It then offers the right card.

Other mail servers

The Other card connects any mailbox with IMAP and SMTP. You need the following information from your mail provider or IT team:

The username and password for SMTP are the same as for IMAP. The IMAP host and the SMTP host must be public addresses. CommSync refuses a host that resolves to a private or reserved address, for example a mail server on your office network.

CommSync sends your password only over an encrypted connection. With SSL, the connection uses TLS from the start. With STARTTLS, CommSync upgrades the connection to TLS before it signs in, and it never continues without TLS. If the mail server does not offer STARTTLS on that port, the connection test fails.

Use SSL on port 993 instead, or ask your mail provider to turn on STARTTLS. The same rule applies to SMTP. If a connected mailbox stops offering STARTTLS, the sync stops and the account shows an error until you change the settings.

CommSync also checks the security certificate of the mail server. On a shared host, mail.<your-domain> often shows the certificate of the host company, not a certificate for your domain. A new domain can wait a day for its own certificate.

When the certificate does not include the host you typed, CommSync looks up the server's own name. It uses that name only when the name points to the same server and the certificate includes it. CommSync then saves that name as the host and tells you. If CommSync finds no such name, use the server name that the control panel of your host shows next to the mail settings.

How CommSync tests an app-password connection

When you click Connect, CommSync tests both the IMAP and the SMTP connection.

If the IMAP test fails, CommSync does not save the account. An error message tells you what went wrong, so you can correct the settings. When the provider refuses the password, the message names the provider and the password it wants, and links the page that makes one. When Google does not know the username, the message names the username.

If only the SMTP test fails, CommSync saves the account and shows a warning. Receiving works, but sending does not work until SMTP connects. To fix it, open Edit on the account card, open Server settings, and correct the outgoing (SMTP) settings. CommSync tests them again when you save. Some cloud networks block outbound SMTP ports, and this rule keeps such a block from stopping the connection.

Choose how much history to import

After the connection succeeds, CommSync asks how much older mail to import: 7 days, 30 days, 90 days, 1 year, All time, or Carry forward only. For each window, CommSync shows an estimate of the storage it uses. A window that does not fit in the storage of your plan is not available.

Carry forward only imports no older mail. New mail syncs from that moment on. You cannot pick a history window for the account later.

The mailbox does not sync until you choose. If you close the dialog with I’ll decide later, the account card in Settings → Email accounts shows Bring in your past email. Click Choose how far back to open the dialog again.

CommSync then imports the window you chose, newest first. Based on the size of your mailbox, this can take a few minutes. Live inbound messages arrive immediately over IMAP IDLE, whatever the progress of the import.

Connect from the iPhone app

Open Settings → Channels → Connect a channel. Select your email provider. Enter the address of the mailbox and the app password. Every provider uses the same form. Open Server settings if your provider uses different server values.

The iPhone app does not have Sign in with Microsoft yet. Connect a Microsoft mailbox on the web. A mailbox that you connect on the web shows in the iPhone app too.

After the connection succeeds, choose how much message history to import. A sending warning means that receiving works, but SMTP needs attention.

Reconnect a mailbox

A signed-in mailbox can stop working. For example, you changed your Microsoft password, you removed CommSync from your Microsoft account, or your IT admin changed a policy. CommSync then stops the sync of that mailbox and shows Action required on the account in Settings → Email accounts.

Click Reconnect. CommSync starts a new sign-in for the same mailbox. Sign in with the same account that you used to connect it. If you sign in with a different account, CommSync refuses the sign-in and shows the address you signed in with. The mailbox keeps its conversations and its sync position.

CommSync makes no more sign-in attempts for that mailbox until someone reconnects it. Repeated failed sign-ins can trigger the risk checks of Microsoft.

For a mailbox that uses an app password, Reconnect opens the password field. Enter the new app password.

Switch from an app password to Sign in with Microsoft

A Microsoft mailbox that you connected with an app password before shows Switch to Sign in with Microsoft in Settings → Email accounts. Click it and sign in with the account of that mailbox. The address you sign in with must be the address of the mailbox.

After the switch, CommSync deletes the stored app password. The mailbox keeps its conversations and its sync position, because it is the same mailbox.

Which folders CommSync reads

CommSync reads the inbox, the Sent folder, and the Spam folder of each account. It finds each folder by the IMAP special-use flag that the server sets, so a folder name in another language works. On Gmail, CommSync reads All Mail instead of the inbox. The Gmail inbox folder hides the mail that Gmail sorts into the Promotions, Updates, Social, and Forums tabs. Gmail names that folder in the language of the account, for example Alle Nachrichten on a German account. CommSync finds it in every language.

If you turned off Show in IMAP for All Mail in the Gmail settings, CommSync reads the Gmail inbox folder instead. Turn the option on to bring the sorted tabs into CommSync.

When a mail server renames a folder, the next sync error shows the old name. CommSync then finds the folder again on the next attempt.

How CommSync stores your credentials

CommSync encrypts an app password at the application layer before it stores it. The encryption uses authenticated AES-256-GCM, and CommSync holds the encryption key separately, so a copy of the database cannot reveal your credentials.

A sign-in with Microsoft or Google gives CommSync tokens, not your password. CommSync keeps them in a separate table and encrypts each one with AES-256-GCM. In production, AWS Key Management Service (KMS) protects the key of those tokens. The server unlocks the key once when it starts and keeps it in memory only. No page, API response, webhook, or log carries a token.

Neon protects message bodies and attachment bytes with database-level encryption at rest, and S3 SSE-AES256 also protects attachment storage.

How inbound email works

CommSync keeps an IMAP IDLE connection open to your mailbox. When a new message arrives at the provider, the server pushes a notification to CommSync — there is no polling delay. CommSync parses the message, matches it to a contact identity, and places it into the appropriate thread within seconds.

A signed-in mailbox uses the same IMAP connection. Its access token lasts about an hour. CommSync gets a new token and reconnects before the old token ends, so the sync does not stop.

Forwarded emails carry extra metadata (Resent-From, X-Forwarded headers, or embedded body blocks). CommSync parses this to identify the original sender. So a forwarded email from a client lands on the client's thread, instead of only on the thread of the colleague who forwarded it.

See Threading for how CommSync decides which thread a message belongs to.

How outbound email works

A mailbox that you connected with Sign in with Microsoft sends through Microsoft Graph. Every other mailbox sends over SMTP with its stored credentials. CommSync updates the delivery status as the send completes.

Mail you send from CommSync also appears in the Sent folder of the mailbox, so your other mail clients show it too. Gmail files it there by itself, and so does Microsoft Graph for a mailbox signed in with Microsoft. For every other provider, CommSync puts a copy in the Sent folder a few seconds after the send, marked as read. When the provider already filed a copy, CommSync adds no second one. If CommSync cannot find a Sent folder on the server, it skips the copy. CommSync still sends the message.

Which account a message goes out from depends on the conversation, and on whether you have nominated a mailbox of your own. If you can use several mailboxes, set one as your default under Settings → Account → Default sending lines. See sending messages for the full picture.

Sender name

Every linked account has a Sender name. That is the display name stamped on the From header for outbound mail, exactly the way Gmail and Apple Mail do it:

From: "Priya Sharma" <priya@northwind.example>

Set it in Settings → Email accounts. When you first connect the account, CommSync pre-fills it with your own name. You can also set it later via Edit on the account card, or with Add a sender name on a card that has none. The form shows a live preview of the header as you type.

The account, and its sender name, belongs to the workspace. Because of that, everyone who sends from a shared mailbox sends under the same name. For role addresses, pick a neutral name — Northwind Support, for example.

What CommSync changes on your mail server

CommSync reads your mailbox. It changes very little on the server:

• Read, star, and archive stay in CommSync. The mail server does not change. Your other mail clients still show the message as before.
• Delete moves the conversation to Trash in CommSync only. The mail on the server does not change. CommSync deletes a conversation 30 days after every reader moved it to Trash. That also does not touch the server.
• Delete permanently deletes the mail on the server too. In the Trash view, this action moves the messages to the Trash of the mail server and removes them there. You cannot undo it. When a teammate can still see the conversation, CommSync removes it for you only. The mail on the server then stays.
• A reply marks the message as answered. Your other mail clients show the reply badge on the message you answered.
• A send adds a copy to the Sent folder on providers other than Gmail and a mailbox signed in with Microsoft (see above).

Channel uniqueness

CommSync can only link an email address to one workspace globally. If you try to link an address that another workspace already owns, you will see a conflict error. To resolve it, you must remove the address from the other workspace first, or the two workspaces must consolidate into one.

When the person who connected a mailbox leaves

A mailbox signs in with the password or the sign-in of the person who connected it. So CommSync disconnects the mailbox when that person leaves the workspace, when an owner or an admin removes them, or when they delete their account. CommSync deletes the stored password or sign-in tokens and stops the sync. The mailbox shows Inactive in Settings → Email accounts, and its conversations stay in the workspace.

To sync the mailbox again, an owner or an admin removes it and connects it again.

How to remove an email account

An owner, an admin, or the member who connected the mailbox can remove it. Go to Settings → Email accounts, find the account, open its ⋯ menu, and click Remove account. CommSync immediately stops the mailbox sync. Threads and messages already in your inbox from that account stay there — removal does not delete historical data.

For a signed-in mailbox, CommSync also deletes its tokens. For a Google sign-in, CommSync first asks Google to revoke the access. Microsoft does not let an app give up its own access. So also remove CommSync from your Microsoft account:

• A work account: open myapps.microsoft.com.
• A personal account: open account.live.com/consent/Manage.

The people who followed those conversations still see them and can open them. The reply box shows "This mailbox was removed from the workspace" instead of Send, because no mailbox can send the reply.

When you connect the same address again, CommSync moves those conversations back onto the account. Replies work again, and new mail joins the same conversations. CommSync matches the old account to the new one by the address it sent from, so a different address never takes over another account's history.