Skip to main content

​
Overview

The Google Workspace integration allows you to connect your Gmail account and Google Calendar to Twenty. Once connected, you can:
  • Sync emails automatically with related contacts and companies
  • View email threads directly in contact and company records
  • Send emails from within Twenty
  • Sync calendar events and meetings
  • Schedule meetings with contacts

​
Prerequisites

Before you begin, make sure you have:
  • A Google Workspace account or personal Gmail account
  • Admin access to your Twenty workspace (for initial setup)
  • For self-hosted instances: Google OAuth credentials

​
Setting Up Google OAuth

​
For Cloud Users

If you’re using Twenty Cloud, the OAuth integration is already configured. Simply connect your account:
1

Open Settings

Navigate to Settings > Accounts in your Twenty workspace.
2

Connect Google Account

Click Connect Google Account and sign in with your Google credentials.
3

Grant Permissions

Review and accept the requested permissions:
  • Read and send emails
  • Access calendar events
  • View contact information
4

Confirm Connection

Once authorized, you’ll be redirected back to Twenty. Your account is now connected!

​
For Self-Hosted Instances

If you’re self-hosting Twenty, you need to set up Google OAuth credentials:
1

Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Gmail API and Google Calendar API
2

Configure OAuth Consent Screen

  1. Navigate to APIs & Services > OAuth consent screen
  2. Select External user type
  3. Fill in the application details
  4. Add the following scopes:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/calendar
3

Create OAuth Credentials

  1. Go to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Web application
  4. Add authorized redirect URIs: 
    https://your-domain.com/auth/google-apis/get-access-token
  5. Copy the Client ID and Client Secret
4

Configure Environment Variables

Add the following to your .env file:
AUTH_GOOGLE_ENABLED=true
AUTH_GOOGLE_CLIENT_ID=your_client_id
AUTH_GOOGLE_CLIENT_SECRET=your_client_secret
AUTH_GOOGLE_CALLBACK_URL=https://your-domain.com/auth/google/redirect
AUTH_GOOGLE_APIS_CALLBACK_URL=https://your-domain.com/auth/google-apis/get-access-token

MESSAGING_PROVIDER_GMAIL_ENABLED=true
CALENDAR_PROVIDER_GOOGLE_ENABLED=true
5

Restart Twenty Server

Restart your Twenty server to apply the changes:
docker-compose restart

​
Email Sync

Once connected, Twenty automatically syncs your Gmail emails:

​
How Email Sync Works

  1. Automatic matching - Twenty matches email addresses with contacts and companies in your CRM
  2. Thread grouping - Related emails are grouped into threads for easy navigation
  3. Real-time sync - New emails are synced within minutes of arrival
  4. Bidirectional sync - Emails sent from Twenty are saved to your Gmail

​
Viewing Emails in Twenty

To view emails for a contact or company:
  1. Open the contact or company record
  2. Navigate to the Emails tab
  3. View all email threads associated with that record
Emails are automatically linked based on sender/recipient addresses. You can also manually link emails to records.

​
Sending Emails

To send an email from Twenty:
  1. Open a contact or company record
  2. Click Send Email in the activity panel
  3. Compose your message
  4. Click Send
The email will be sent from your connected Gmail account and saved to your Sent folder.
Required Scopes for Sending Emails:
  • https://www.googleapis.com/auth/gmail.send
  • https://www.googleapis.com/auth/gmail.compose
If you don’t see the option to send emails, you may need to reconnect your account with the correct scopes.

​
Calendar Sync

The Google Calendar integration syncs your calendar events with Twenty:

​
Features

  • Two-way sync - Events created in Twenty appear in Google Calendar and vice versa
  • Attendee linking - Calendar attendees are automatically linked to contacts
  • Meeting scheduling - Schedule meetings directly from contact records
  • Availability checking - View your calendar when scheduling meetings

​
Managing Calendar Events

  1. Navigate to the Calendar view in Twenty
  2. Create, edit, or delete events
  3. Changes sync automatically with Google Calendar

​
Permissions and Scopes

The Google integration requires the following OAuth scopes:
ScopePurpose
gmail.readonlyRead emails from your Gmail account
gmail.sendSend emails on your behalf
gmail.composeCreate draft emails
calendarAccess and manage calendar events
userinfo.emailIdentify your Google account
Twenty only requests the minimum permissions needed. Your credentials are encrypted and never shared with third parties.

​
Troubleshooting

​
Emails Not Syncing

If emails aren’t appearing in Twenty:
  1. Check that your Google account is still connected in Settings > Accounts
  2. Verify that the email addresses match contacts in your CRM
  3. Check the sync status in account settings
  4. Try disconnecting and reconnecting your account

​
Calendar Events Missing

If calendar events aren’t syncing:
  1. Ensure calendar sync is enabled in your account settings
  2. Check that you’ve granted calendar permissions
  3. Verify the calendar is not marked as “private” in Google Calendar

​
Authentication Errors

If you see authentication errors:
  1. The OAuth token may have expired - reconnect your account
  2. For self-hosted instances, verify your OAuth credentials are correct
  3. Check that redirect URIs match exactly in Google Cloud Console

​
Implementation Details

The Google Workspace integration is implemented in the Twenty server codebase:
  • OAuth flow: packages/twenty-server/src/engine/core-modules/auth/controllers/google-auth.controller.ts:27
  • Email sync: packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/
  • Calendar sync: packages/twenty-server/src/modules/calendar/calendar-event-import-manager/drivers/google/

Need Help?

Join our Discord community for support and to share feedback.

Build docs developers (and LLMs) love

Get started for freeTalk to us