Gmail & Calendar sync

The same Google OAuth client that signs you in also reads your mailbox and calendar, read-only, and turns threads and meetings into contacts, companies and a timeline automatically. It is always on — there is no feature flag to enable — and it uses the two read-only scopes added to the existing Google provider, so there's no extra redirect URI to register.

Forward-only

Nothing from before a mailbox was first seen is imported. Gmail records the current history position on its first pass and imports nothing from the past; Calendar reads from now onwards. There is no backfill window to configure.

What it creates

For each new external person on a thread or meeting, the sync can create a contact and, from their email domain, a company — then queue the agent to identify them. Two independent switches on Settings → Connections control this:

Switch	Off means
Meetings	Keep attributing meetings to existing records, but stop creating new contacts / companies from calendar attendees
Email	Same, for email threads

Useful once your CRM is populated and you'd rather add new accounts deliberately.

Not every address on a thread is a person

One gate stands between what Google returns and what becomes a record. It throws away three kinds of thing before it gets to a lead:

1. Us — the allow-list domains and everyone in the user table.
2. A decision a rep made — a suppressed contact or a suppressed domain.
3. An address no human has ever read — shared calendars (group.calendar.google.com), meeting rooms, imported ICS feeds, and opaque machine local-parts like a bare UUID. It matches the host, never a substring, so someone's real calendar.acme.com is unaffected.

Shared inboxes and invitation senders — sales@, noreply@, bookings@ — are a separate list, matched on the local part. That's why support@acme.com never becomes a lead at a company you do genuinely sell to.

Deleting a contact is remembered

Deleting a synced contact isn't enough on its own — the next message from that person would put them straight back. So the delete writes a suppression keyed on the lowercased email address, and the same gate that drops suppressed domains drops that address from contact creation, company auto-creation and thread attribution at once. Adding the contact back by hand lifts the suppression. See Contacts.

Status and control

Settings → Connections shows a Connected / Needs attention indicator and the last check time.

• Check now pulls the latest immediately instead of waiting for the scheduled pass.
• If Google stops returning a refresh token, the card tells you to sign out and back in rather than leaving the sync silently stale.
• Revoke Google access stops the sync going forward; nothing already on a record is touched.
• Delete synced data removes every email and meeting the sync itself brought in. The next check starts from now, so nothing deleted comes back on its own.

Deployment

Variable	Required	Notes
CRON_SECRET	In deployed environments	Bearer guard on POST /internal/sync/google. Minimum 16 characters; the route fails closed if unset, so locally the cron simply never runs.

Enable the Gmail API and the Calendar API on the Google Cloud project, and set the consent screen to Internal if you're on Google Workspace — gmail.readonly is a restricted scope, and going External later means full OAuth verification plus an annual security assessment.

SSO reps

Someone who signed in through an identity provider is not required to connect Google to use the CRM — Gmail and Calendar are a connection for them, offered on Settings → Connections, not a condition of entry.