Email & Calendar Synchronization
Relevant source files
The following files were used as context for generating this wiki page:
- packages/twenty-docs/docs.json
- packages/twenty-shared/src/constants/DocumentationPaths.ts
- packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md
- packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
- packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
- README.md
Email and Calendar synchronization in Twenty is a core capability designed to integrate external communication and scheduling data directly into the CRM. This system allows users to connect multiple mailboxes, track email activity across various objects (such as People and Companies), and manage schedules through synchronized calendars.
The synchronization mechanism ensures that communications are logged as activities within the record timeline, providing a unified view of interactions. This is supported by specific data model capabilities that allow for the tracking of email history and the booking of meetings directly within the Twenty interface.
Sources: packages/twenty-docs/docs.json:115-139, README.md:95-103
Core Capabilities
The synchronization system is divided into two primary functional areas: Mailbox and Calendar. These are exposed to users through the interface and managed via backend core modules.
Synchronization Features
| Feature | Description |
|---|---|
| Mailbox Sync | Support for connecting multiple mailboxes per user and importing emails. |
| Activity Tracking | Automatic tracking of email interactions on relevant CRM objects (Contacts, Companies, etc.). |
| Calendar Sync | Real-time synchronization of meetings and availability with external providers. |
| Inbound Automation | Capabilities for auto-replying to inbound emails via workflows. |
| Visibility Control | Settings to limit the number of imported emails and manage record visibility. |
Sources: packages/twenty-docs/docs.json:115-139, packages/twenty-docs/docs.json:173-180
Integration Architecture
Twenty uses specialized connection providers to facilitate synchronization with external services. This involves OAuth setups and specific logic functions to handle data flow between Twenty and third-party systems like Gmail or Outlook.
The diagram shows the flow of data from an external provider through the connection layer into the Twenty CRM activity timeline.
Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:54-65, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:120-125
Data Model & Activity Tracking
Synchronized emails and calendar events are represented within Twenty as activity records. These records are linked to standard objects through relationships.
Implementation Patterns
- Automatic Relations: Custom and standard objects automatically receive attachments, notes, tasks, and timeline entries, which include synced emails.
- Person Mapping: Synced communications are primarily mapped to a
Personobject. If a sender/receiver is recognized, the activity is linked to that record. - Timeline View: All synced emails appear in the record's timeline to provide context for sales and support interactions.
Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:162-168, packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md:13-25
Key Fields for Synced Records
| Field | Type | Description |
|---|---|---|
createdAt | DateTime | Timestamp when the sync record was created in Twenty. |
updatedAt | DateTime | Timestamp of the last update to the sync record. |
amount | Currency | Often used in related Opportunity records synced via email logic. |
closeDate | DateTime | Used for calendar events or opportunity milestones. |
Sources: README.md:54-61, packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md:52-65
Workflow Automation
Synchronization triggers can be used within Twenty Workflows to automate CRM actions based on incoming communication.
This flow illustrates how a synchronized email can trigger automated tasks or notifications within the workspace.
Sources: packages/twenty-docs/docs.json:160-180, packages/twenty-shared/src/constants/DocumentationPaths.ts:168-185
Configuration and Constraints
Synchronization is subject to specific configuration options and plan-gated features within the Twenty platform.
- Mailbox Limits: Users can connect multiple mailboxes, but the system allows for limiting the scope of imported emails to maintain data hygiene.
- Permissions: Visibility of synced emails is governed by Workspace permissions. Row-level security (RLS) can be applied to restrict access to sensitive communications, typically available on higher-tier plans (Organization plan).
- Data Residency: Depending on the hosting configuration (Cloud vs. Self-host), synchronized data residency may be restricted to specific regions like the EU.
Sources: packages/twenty-docs/docs.json:130-138, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:175-185, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:214-222
Summary
Email and Calendar Synchronization provides the critical link between external communication tools and the Twenty CRM. By mapping external data to the internal data model, Twenty ensures that every interaction is captured within the relevant business context. The system leverages OAuth connections, automated activity timelines, and workflow triggers to create a seamless experience for managing leads and customer relationships.