Documentation Communication channels Gmail

Channels integration

Gmail

Gmail integration overview
  • CategoryChannels
  • AuthOAuth

Overview

Gmail connects on /channels/email through Google OAuth. The page shows a four-provider picker (Google, Google Workspace, Outlook, Custom Domain); pick Google for a personal Gmail account or Google Workspace for an inbox on your own business domain. The OAuth popup opens in a new window, you authorise MessageMind, and MessageMind starts watching the inbox so inbound emails land in the shared inbox the AI works from. When an email is a website form notification sent from a noreply address, MessageMind extracts the real submitter from the body and opens the conversation against them.

What MessageMind can do with it

  • Pick between Google (Gmail · personal account) and Google Workspace (For your business domain) on the connect card; both OAuth paths are supported, and MessageMind activates Gmail inbox watching on connect.
  • Add more than one mailbox from the Add inbox tab, so a team can run several Gmail accounts side by side under one tenant.
  • Detect when an inbound email is a form notification, extract the submitter's name, email, phone and other labelled fields, and open the thread against the submitter rather than the form service's noreply address.
  • Create the submitter as a contact with the mapped fields before the conversation is opened, so Contact Created automations see the full record.
  • Deduplicate the same form submission when the form copies several mailboxes, so one submission becomes one contact and one conversation.
  • Fall back to an AI pass for form notifications the deterministic parser cannot read (table-only HTML, unusual labels, unsupported language).

Requirements

  • A Google account (personal Gmail or Google Workspace) with access to the mailbox you want to connect.
  • Permission to grant Gmail access to MessageMind on the Google consent screen. On a Workspace account, an admin may need to allow third-party app access first.
  • Browser popup permission for the MessageMind dashboard; the OAuth window opens as a popup.

How to connect

  1. Open MessageMind and go to /channels/email. You will see the Connect Email Provider card.
  2. Pick Google (Gmail · personal account) or Google Workspace (For your business domain) depending on the mailbox.
  3. The OAuth popup opens. Sign in to Google, pick the exact mailbox, review the requested scopes and click Allow.
  4. The popup closes. MessageMind shows 'Email Connected Successfully!' and starts Gmail inbox watching on the mailbox; a 'Gmail inbox watching activated successfully.' toast confirms the subscription.
  5. To add another Gmail mailbox, click the Add inbox tab and run the same OAuth flow for the next account.

Authentication and permissions

Mechanism
Google OAuth 2.0 opened in a popup window from the MessageMind dashboard. Google (Gmail) and Google Workspace go through two different OAuth clients on Google's side; the picker on /channels/email routes you to the right one.
Credentials
An OAuth refresh token issued by Google for the connected mailbox, stored on your MessageMind tenant and used server-side to call Gmail's API and keep inbox watching renewed.

Available data and actions

Reads

  • Inbound Gmail messages, including envelope sender, subject, text body and HTML body.
  • Each inbound message's Gmail message id, used to tie the lead ingest row back to the originating email.

Writes

  • A new or updated contact with the submitter's name, email, phone and any other labelled fields the form provided.
  • A conversation thread for the submitter, keyed on the real person rather than on the form service's address.
  • Custom field entries on the contact for every other labelled form field, matched case-insensitively on the trimmed key so a repeated submission updates in place.

AI agent use cases

  • A website quote form emailing [email protected] becomes a conversation with the actual customer, with their phone and quote details already on their contact.
  • The same form submission copied to two mailboxes creates one contact and one thread, not two.
  • A table-only HTML form notification is still turned into a lead through the AI fallback when the deterministic parser cannot label its fields.

Configuration

  • Owner-specific form handlers can override the generic behaviour for a tenant: a handler can mark incoming leads as contact-only (contact created, no inbox thread), switch the generic detector off entirely, or decide what happens when a known person submits again (overwrite the mapped fields and rerun the Contact Created automations).
  • The form-lead detector drops placeholder values such as dashes, N/A, Not specified, TBD and To be confirmed before writing them onto the contact.
  • A phone the central contact creator rejects as invalid is retried once with the raw value saved as a Phone Number custom field, so a junk phone never costs the lead.

Example workflows

Form notification routed to the real submitter

  1. A website form emails your Gmail mailbox from a noreply address with the submitter's details written as labelled lines in the body.
  2. MessageMind flattens the body (HTML or text), reads the labelled lines, and extracts the submitter's email, name, phone and the other fields.
  3. The lead is handed to the central contact creator, which creates the person (or merges into an existing contact) with their mapped fields and runs Contact Created automations.
  4. The conversation thread is opened against the submitter's address, so replies go to them, not to the form service.
  5. A copy of the same submission sent to another mailbox is detected by its submission key, the counter is incremented, and no second contact or thread is opened.

Limitations

  • The connection authorises MessageMind to read and act on the one Gmail mailbox you connect; this page documents only what is visible in the inbound-handling code.
  • The deterministic form parser needs at least two labelled lines, and requires an email the form explicitly labelled or a clearly automated sender; otherwise the email is treated as ordinary correspondence.
  • The AI fallback for form extraction only runs when the sender looks automated and another address is visible in the body, so an ordinary customer email never spends an AI call there.

Troubleshooting

The OAuth popup opens and closes without connecting.

The browser popup was blocked, or you closed it before Google returned the authorisation code. Allow popups for the MessageMind dashboard origin and re-click Google (or Google Workspace) on /channels/email.

Google says the app is not allowed on this Workspace.

A Workspace admin has restricted third-party app access. The admin needs to allow the MessageMind client in Google Admin, Security, API controls. Once allowed, retry Google Workspace on /channels/email.

The toast says 'Failed to activate Gmail inbox watch.'

The OAuth succeeded but Gmail refused the watch subscription (usually a quota or scope issue). Reconnect from /channels/email so a fresh OAuth is run; if it persists, confirm the Google account still has permission to use Gmail.

A form that emails you keeps piling onto the form service's noreply contact.

The form body does not carry a labelled email and the sender is not clearly automated, so the detector cannot be sure who the real person is. Make the form include a labelled Email field in the body, or contact support to add an owner-specific handler for that form.

A valid phone from the form is missing on the created contact.

The central creator rejected the phone as invalid for your region; MessageMind retries without the phone identity and keeps the raw value under a Phone Number custom field. Review the raw value on the contact and fix the formatting.

Disconnect and reconnect

  • On /channels/email, pick the Gmail mailbox tab and click Disconnect. MessageMind clears the stored OAuth tokens for that mailbox and shows 'Email disconnected successfully!'. The Gmail inbox watch is stopped.
  • On Google's side, you can also revoke MessageMind at myaccount.google.com, Security, Third-party apps with account access.
  • To reconnect, run the Google (or Google Workspace) OAuth again from /channels/email. Previously received emails already in MessageMind stay in the inbox.