Skip to main content

Ouath Touchpoint Sync

(NOTE: Touchpoints are only scoped to Emails for now, but we'll be adding more channels over time)

Chuff, as a Customer Relationship Management (CRM) platform, leverages OAuth to provide seamless and secure email synchronization capabilities. This document explains how Chuff utilizes OAuth-granted permissions to enhance your contact management and communication tracking, while ensuring your data privacy and control.

What is Email Contact Synchronization?​

Email contact synchronization is the process of integrating your email account with Chuff to automatically capture and organize email communications related to your contacts. This means that emails sent from or received in your connected email account are mirrored within Chuff, allowing you to:

  • Track communication history: See a complete timeline of interactions with your leads and customers directly within their contact profiles.
  • Centralize contact data: All relevant email correspondence is accessible in one place, providing a holistic view of your relationships.
  • Improve team collaboration: Teams can easily view shared communication histories, ensuring everyone is up-to-date on client interactions.

How Chuff Uses OAuth for Email Sync​

Chuff uses OAuth to securely access your email data without ever requiring your email password. When you connect your email account (e.g., Gmail or Outlook) to Chuff, you grant specific permissions through the OAuth flow. This authorization allows Chuff to:

  • Fetch Email Messages: Chuff retrieves emails from your "Inbox" and "Sent Items" folders. This is crucial for building a comprehensive communication history.
  • Identify Contacts: By analyzing the "From," "To," and "Cc" fields of emails, Chuff identifies the contacts involved in conversations. It then attempts to match these email addresses with existing contacts in your CRM or create new contact entries as needed.
  • Store Email Content: The content of your emails (both HTML and plain text) is securely stored within Chuff's database and Amazon S3 (for the full message body). This allows for quick retrieval and display of past communications.
  • Deduplicate and Organize: Chuff uses RFC Message IDs to prevent duplicate email entries and organizes emails into conversation threads, providing a clear and chronological view of interactions.
  • Trigger Automated Workflows: Synced emails can trigger automated actions within Chuff, such as updating contact statuses or initiating follow-up tasks.

The Technical Flow of Email Synchronization​

The core logic for email synchronization resides within the TouchpointService class. Here's a simplified breakdown:

  1. OAuth Authorization: Users connect their email accounts (Gmail or Microsoft Outlook) via OAuth, granting Chuff the necessary permissions (e.g., https://www.googleapis.com/auth/gmail.readonly for Gmail, or similar scopes for Microsoft Graph API).
  2. Fetching Messages:
    • For Gmail, the parse_gmail_messages method utilizes the Gmail API to retrieve messages from "SENT" and "INBOX" labels.
    • For Microsoft Outlook, the parse_msft_messages method uses the Microsoft Graph API to fetch messages from "Inbox" and "SentItems" folders.
    • Only messages received/sent after a specific date (defaulting to a two-year window) are fetched to ensure efficient synchronization.
  3. Contact Identification and Processing:
    • The process_contacts_into_map method extracts email addresses and names from the "From," "To," and "Cc" fields of each email.
    • It attempts to enrich contact information (e.g., by extracting first and last names) and creates or updates PersonView entries in the Chuff database for these contacts. Generic emails (like [email protected]) are filtered out.
  4. Deduplication: Before storing, Chuff checks if an email with the same rfc_message_id (a unique email identifier) already exists to prevent redundant entries.
  5. Storing Touchpoints: Each unique email is stored as a Touchpoint record in the database. This record includes metadata like sender, recipients, subject, timestamp, and a reference (s3_key) to the full email content stored securely in Amazon S3.
  6. Dispatching Hooks: After successful storage, various "hooks" are dispatched. These hooks can trigger further actions within Chuff, such as updating campaign statuses or initiating agent-based workflows.

User Control and Data Privacy 🔒​

Chuff is committed to data privacy and provides users with complete control over their synced email data.

  • Data Deletion: The purge_touchpoints_for_account method allows users to easily delete all synced email touchpoints associated with a specific connected email account. This action removes the email records from Chuff's database, associated agent hooks, and the stored email content from Amazon S3. Your control over your data is further detailed in our documentation: https://docs.chuff.co/docs/delete-data
  • Consent: Synchronization only occurs after explicit user consent through the OAuth authorization process.
  • Limited Scope: Chuff requests the minimum necessary Gmail or Microsoft Graph API scopes to perform email synchronization, focusing solely on reading email metadata and content relevant to contact interactions.

By leveraging OAuth, Chuff ensures a secure, efficient, and user-controlled method for integrating email communications into your CRM workflow.