Messaging

A Gmail integration connects a Gmail mailbox to Mobius so loops can receive message events, search mail, read threads, send replies, create drafts, and update message labels.

Use Gmail when incoming mail should start a durable run or when the run needs to respond from the connected mailbox. Gmail sync is driven by provider state, so a first sync can take a short moment before the first event appears.

For the shared Google credential model, see Google integrations.

Capability map

Connect Gmail

OAuth mode is best for personal Gmail mailboxes. Service-account mode is best for Google Workspace mailboxes with domain-wide delegation. Gmail can still appear in the provider catalog when Google OAuth is not configured, but the OAuth button only appears on deployments with shared Google OAuth credentials.

Products that embed Mobius can add two optional fields to the OAuth connect body: return_url (an absolute HTTPS URL whose origin is on the organization's return-origin allowlist) and client_state (an opaque value echoed back on return). When return_url is present, the browser is redirected there after the OAuth callback instead of landing on the Mobius app. Omit both fields for the standard flow. See embedded OAuth return for allowlist setup, callback fields, failure outcomes, and fallback behavior.

Permissions

OAuth mode uses the scopes required for the Gmail actions enabled in the deployment. Reading message bodies, modifying labels, and sending mail require Gmail user-data scopes, and Google classifies broad mailbox scopes as restricted. If your Workspace admin blocks unreviewed apps, approve the Mobius OAuth app before connecting.

Service-account mode needs domain-wide delegation in Google Workspace. Grant the service account the Gmail scopes Mobius uses, then connect the service account JSON and mailbox address in the app.

Actions

gmail.label.list
gmail.message.archive
gmail.message.create_draft
gmail.message.get
gmail.message.list
gmail.message.mark_read
gmail.message.mark_unread
gmail.message.modify_labels
gmail.message.reply
gmail.message.send
gmail.message.trash
gmail.message.untrash
gmail.thread.get
gmail.thread.list

Use gmail.message.get or gmail.thread.get before replying if the run needs full body context. Use draft creation when a human should review mail before it is sent.

Events

gmail.message.received

Use gmail.message.received to start intake loops from new mail. The event payload contains a stable message reference and a canonical event.email object marked security.origin = "external_email_untrusted". Subject and snippet fields are bounded and neutralized before they reach the run, with obvious prompt-injection or exfiltration patterns surfaced under security.injection_signals. Fetch the full message or thread inside the run when you need body content; Gmail read actions return the same canonical email object alongside compatibility body fields. Agent turns receive canonical untrusted email in a dedicated external-mail evidence block separated from trusted instructions.

Deployed Mobius environments provision the Google Pub/Sub topic, push subscription, webhook token, and Cloud Run environment variables through Terraform. Without Pub/Sub, Gmail still emits the same event from the regular sync cadence.

Troubleshooting

New messages do not start runs immediately

Wait for the first sync to finish. Gmail sync records provider state before it emits new message events, so historical mail does not start loops when you first connect the mailbox.

OAuth succeeds but Gmail actions fail

Check whether the Google account or Workspace admin granted the Gmail scopes needed by the action. Sending, label modification, and full message reads need more access than listing message metadata.

Pub/Sub callbacks are not arriving

The webhook endpoint must be reachable by Google Pub/Sub, and the deployment must have the Pub/Sub topic, subscription, callback token, and Cloud Run environment configured. Without Pub/Sub, use the sync cadence and inspect source events.

Next

• Use source events to debug incoming mail.
• Return OAuth to an embedded product with embedded OAuth return.
• Add human review with interactions.
• Store durable outputs as artifacts.