How to Connect Gmail and Outlook to a Self-Hosted Twenty CRM
Step by step setup for connecting Gmail, Google Calendar, and Microsoft 365 to a self-hosted Twenty CRM, including OAuth app setup, Google verification rules, sync limits, and real costs.

Connecting your team inboxes to a self-hosted Twenty CRM takes about an hour for Google and half that for Microsoft, but only if you make one decision correctly up front: whether your Google OAuth consent screen should be internal or external. Get that wrong and every user sees an "unverified app" warning, or you burn months on a Google verification process you never needed. This guide covers the full setup for Gmail, Google Calendar, and Microsoft 365 on a self-hosted Twenty instance, the limits of the sync engine, and what the whole thing costs.
How Twenty email and calendar sync actually works
Before touching any console, understand what you are turning on. Twenty is an open-source CRM with a built-in messaging and calendar sync engine, not a plugin you bolt on later.
Each user connects their own mailboxes from Settings, then Accounts. Per the Twenty documentation:
- Unlimited accounts per user. One person can connect several mailboxes.
- True mailboxes only. The account needs its own login. Aliases that forward into another inbox cannot be connected; the original mailbox must be linked instead.
- Three visibility levels. Metadata only (participants, date, time), subject and metadata, or all content including the body. This is set per account, so your CEO can share subjects while a sales rep shares everything.
- Contact auto-creation. Off, sent and received, or sent only. New external contacts are created automatically and linked to a Company record by email domain, creating the company if it does not exist.
- Internal emails are excluded by default. Messages between colleagues on the same domain stay out of the CRM unless a workspace admin enables syncing them (on older versions under Settings, then Communication; on recent versions, enable Advanced mode in Settings and look under General, then Security).
- Folder selection. Sync only the folders you choose: inbox, sent, custom folders like Archive or Receipts, with exclusions. Twenty has no CC address for selective logging like some CRMs offer; folders are the mechanism.
- Attachments. The documentation lists email attachment sync as coming in H1 2026, a window that has now passed while the docs still say it. Treat attachments as unshipped until the docs or the release notes for your Twenty version say otherwise, and verify before promising it to your team.
On timing: after the initial import, new messages sync about every five minutes. The initial import runs at roughly 400 messages per minute because of Gmail API rate limits, so a mailbox with 10,000 emails takes about 25 minutes to backfill. Calendar sync works the same way: meetings with external participants are pulled in and linked to People and Company records automatically.
The Google decision: internal app or verified public app
This is the part every other tutorial skips, and it is the part that bites teams later.
Twenty asks Google for these scopes when a user connects: email, profile, gmail.readonly, gmail.send, gmail.compose, calendar.events, and profile.emails.read (see the scopes in the Twenty source code). Google classifies gmail.readonly and gmail.compose as restricted scopes, the most heavily regulated category in the Gmail API scope list.
That classification has consequences, per Google's verification FAQ:
- An unverified app requesting sensitive or restricted scopes shows users an "unverified app" warning screen and is capped at 100 new users over the lifetime of the Google Cloud project. Exhaust the cap and Google sign-in stops working.
- Restricted scope verification takes around six weeks, requires a third-party security assessment, and must be renewed. Brand verification alone takes two to three business days; sensitive scope verification around ten.
For a self-hosted CRM used by one company, all of that is avoidable. Google states plainly that verification is not needed for internal-use apps: if your Google Cloud project belongs to your Google Workspace or Cloud Identity organization and you set the OAuth consent screen user type to Internal, there is no warning screen, no 100-user cap, and no security assessment. Only accounts in your own Workspace domain can connect, which is exactly what a company CRM needs.
Use this checklist to pick your path:
- Your team is on Google Workspace and only your staff will connect. Choose Internal. Done. No verification.
- Your team uses free @gmail.com addresses. Internal is not available. Use External with publishing status Testing: users click through a warning screen and you are capped at 100 authorizations, which is fine for a 15-person company but a hard ceiling.
- You are building a product that connects other companies Gmail accounts. You need full restricted-scope verification and the security assessment. Budget roughly two months.
- You are on Microsoft 365 only. None of this applies; skip to the Microsoft section below.
Connect Gmail and Google Calendar step by step
Assumes Twenty is already running via Docker Compose. If not, do that first; our self-hosting guide for Twenty covers installation, backups, and updates.
- Create a Google Cloud project. In the Google Cloud console, create a project owned by your Workspace organization.
- Enable three APIs: Gmail API, Google Calendar API, and People API.
- Configure the OAuth consent screen. Set the user type to Internal (per the decision above). Give the app a name and logo; your colleagues will see this screen when they connect.
- Create OAuth credentials. Under Credentials, create an OAuth 2.0 Client ID of type Web application. Add two authorized redirect URIs:
https://your-crm-domain.com/auth/google/redirect(for sign-in with Google)https://your-crm-domain.com/auth/google-apis/get-access-token(for email and calendar sync)
- Set the variables in Twenty. By default, Twenty is configured from the admin panel rather than the
.envfile. Go to Settings, then Admin Panel, then Configuration Variables, find the Google Auth section, and set:
MESSAGING_PROVIDER_GMAIL_ENABLED=true
CALENDAR_PROVIDER_GOOGLE_ENABLED=true
AUTH_GOOGLE_CLIENT_ID=your-client-id
AUTH_GOOGLE_CLIENT_SECRET=your-client-secret
AUTH_GOOGLE_CALLBACK_URL=https://your-crm-domain.com/auth/google/redirect
AUTH_GOOGLE_APIS_CALLBACK_URL=https://your-crm-domain.com/auth/google-apis/get-access-token
- Connect a mailbox. In Settings, then Accounts, click Add account and choose Continue with Google. Pick the visibility level and contact creation setting before finishing.
- Repeat for each user. Every team member connects their own mailbox; admins cannot connect mailboxes on behalf of others.
These steps and variable names come straight from the Twenty self-host configuration docs. One operational note from the same page: calendar and messaging sync run as background jobs in the worker container. If accounts connect but nothing syncs, check that your worker container is running before blaming OAuth.
Connect Microsoft 365 and Outlook step by step
The Microsoft path is simpler because there is no restricted-scope verification regime for an internal company app.
- Register an app in Microsoft Entra. In the Entra admin center, go to Entra ID, then App registrations, then New registration. Choose single tenant unless outside organizations will connect. Record the Application (client) ID from the Overview page, as described in Microsoft's registration guide.
- Add redirect URIs for the web platform:
https://your-crm-domain.com/auth/microsoft/redirecthttps://your-crm-domain.com/auth/microsoft-apis/get-access-token
- Create a client secret under Certificates and secrets. Copy the value immediately; it is shown once.
- Check the API permissions. Twenty requests
openid,email,profile,offline_access,Mail.ReadWrite,Mail.Send,Calendars.ReadWrite, andUser.Read. If your tenant blocks users from consenting, they will hit error AADSTS90094 when connecting. The fix is one click: an administrator opens the app registration, goes to API permissions, and selects Grant admin consent for your tenant. - Set the variables in Twenty, same admin panel as before:
MESSAGING_PROVIDER_MICROSOFT_ENABLED=true
CALENDAR_PROVIDER_MICROSOFT_ENABLED=true
AUTH_MICROSOFT_ENABLED=true
AUTH_MICROSOFT_CLIENT_ID=your-application-id
AUTH_MICROSOFT_CLIENT_SECRET=your-client-secret
AUTH_MICROSOFT_CALLBACK_URL=https://your-crm-domain.com/auth/microsoft/redirect
AUTH_MICROSOFT_APIS_CALLBACK_URL=https://your-crm-domain.com/auth/microsoft-apis/get-access-token
- Connect accounts from Settings, then Accounts, Continue with Microsoft.
Other providers: IMAP, SMTP, and CalDAV
For any provider that is not Google or Microsoft, Twenty supports direct IMAP for incoming mail, SMTP for sending, and CalDAV for calendars. The connection screen validates the settings immediately.
Two catches worth knowing:
- SSRF protection blocks private IPs by default. If your mail server runs on an internal network, Twenty refuses the connection. Add its hostname to
OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTSin your.envfile. Do not use the oldOUTBOUND_HTTP_SAFE_MODE_ENABLED=falseescape hatch; remove it if you find it. - System email is a separate configuration. Invitations, password resets, and workflow notifications use
EMAIL_DRIVER=smtpwith a provider like Resend, or Gmail or Office365 SMTP with an app password. This has nothing to do with mailbox sync and is a common source of confusion.
What it costs
The sync itself has no per-email fee on either side. The cost question is self-host versus Twenty Cloud.
From the Twenty pricing page: the Cloud Pro plan is $9 per user per month and includes Google and Microsoft email and calendar sync with unlimited connected accounts per user. Organization is $39 per user per month, and Enterprise starts at $50,000 per year. On cloud, Twenty operates the OAuth apps, so the entire Google and Microsoft setup above is done for you.
Self-hosting makes the software free but moves the work to you. A worked example for a 10-person team:
- Twenty Cloud Pro: 10 users x $9 = $90 per month, $1,080 per year. Setup time for email sync: minutes.
- Self-hosted: a suitable VPS runs roughly $20 to $40 per month ($240 to $480 per year), plus the hour of OAuth setup in this guide, plus ongoing upgrades and backups. Our Twenty self-hosting cost breakdown goes line by line.
Google API usage is not a real cost driver at CRM scale. Google updated Gmail API quotas on May 1, 2026: 1,200,000 quota units per minute per project, 6,000 per minute per user, and an 80,000,000-units-per-day billing threshold before charges apply. The new limits bind Cloud projects created on or after that date; projects that used the API between November 2025 and April 2026 keep their previous quotas. A messages.get call costs 20 units. Even syncing ten busy mailboxes stays far inside the free tier.
The honest summary: for a 10-person team, cloud costs about $600 to $840 more per year than the VPS and saves you the maintenance burden. Self-hosting pays off when you need data residency, deep customization, or you are already running other open-source tools and have the operations habit. If you are comparing against HubSpot seats instead, the math changes completely; see our Twenty vs HubSpot cost comparison.
Common mistakes
- Trying to connect an alias. Aliases fail silently or cannot be added. Connect the true mailbox that owns the login.
- Leaving the Google consent screen in External Testing mode for a Workspace team. You get warning screens and a 100-user cap for no reason. Switch to Internal.
- Assuming colleague emails are missing because sync broke. Internal same-domain emails are excluded by design. An admin must opt in workspace-wide.
- Expecting instant history on a big mailbox. At about 400 messages per minute, a 50,000-email inbox needs roughly two hours for the initial import. New mail still arrives every five minutes during it.
- Blaming OAuth when the worker is down. Sync runs on background jobs in the worker container. Check it first.
- Connecting an internal mail server without the SSRF allowlist. Private IPs are refused by default.
- Promising attachments. The docs still list attachment sync as coming in H1 2026, a date that has passed. Verify against your version first.
When Twenty email sync is the wrong choice
Be honest with yourself about these cases:
- You need attachment ingestion today. Contracts, invoices, and CVs attached to emails are exactly what legal and finance teams want in the CRM. Until attachment sync ships, this is a real gap.
- You want CC-based selective logging. HubSpot-style "forward this one email to the CRM" does not exist in Twenty; folder selection is the substitute. If per-email control matters, a HubSpot migration needs expectation-setting with the team first.
- You need a shared support inbox with triage and SLAs. That is help desk territory, not CRM. A tool like Chatwoot fits better, and both can run side by side.
- Your real goal is outbound campaigns. Mailbox sync logs conversations; it does not send sequences or newsletters. Use a dedicated tool for that and keep Twenty as the record.
If what you actually need is automated follow-up on top of synced conversations, that is a workflow problem; our Twenty workflow automation guide covers what the built-in engine can and cannot do. If bookings drive your pipeline, our guide to connecting Cal.com bookings to Twenty with webhooks and n8n shows the same record-creation pattern for meetings. When you outgrow built-in workflows, multi-step sequences across Twenty, email, and your other tools are exactly the kind of business automation we implement with n8n and Make.
Frequently asked questions
Does Twenty sync emails in real time? Close to it. After the initial import (about 400 messages per minute), new emails sync roughly every five minutes. Calendar events sync on the same cadence.
Can I connect more than one mailbox? Yes. There is no limit on connected accounts per user, but each must be a true mailbox with its own login. Aliases cannot be connected directly.
Do I need Google app verification for a self-hosted Twenty? Not if your team is on Google Workspace and you set the OAuth consent screen to Internal. Internal apps skip verification, the warning screen, and the 100-user cap entirely. Free Gmail accounts require External mode, which carries the cap.
Does Twenty sync email attachments? Not as of this writing. The documentation still lists attachment sync as coming in H1 2026 even though that window has passed, so treat it as unshipped and check the docs and your Twenty version before planning around it.
Can I connect a shared inbox like sales@? Yes, if it is a real mailbox with its own credentials. Any team member can connect it to their workspace account, and multiple people can connect the same mailbox.
Will this work with personal Gmail accounts? Yes, via an External consent screen in Testing mode. Users see a warning screen when connecting, and the project is capped at 100 authorized users.
Where to go from here
Email sync is the highest-leverage configuration in a new Twenty deployment: it turns an empty CRM into a living record of every customer conversation in the first week. If you would rather not run the OAuth consoles, upgrades, and backups yourself, our managed open-source stack service deploys and operates Twenty for your team, email and calendar sync included, on infrastructure you control.
About AI Agents Plus Editorial
AI automation expert and thought leader in business transformation through artificial intelligence.



