Integrations

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

Use Gmail when an agent should read or answer mail 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 agent needs full body context. Use draft creation when a human should review mail before it is sent.

Events

gmail.message.received

gmail.message.received is the new-mail event. Its 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 an agent sees them, with obvious prompt-injection or exfiltration patterns surfaced under security.injection_signals. Fetch the full message or thread inside the turn 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.

Gmail can receive new-message notices immediately or find them during its regular sync. Either path emits the same event, so a missing immediate notice does not change the event contract.

Troubleshooting

New messages do not appear immediately

Wait for the first sync to finish. Gmail sync records provider state before it emits new message events, so historical mail is not replayed 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

Inspect source events first. If messages appear after a delay, Gmail's regular sync is working while immediate delivery is not. Send the event time and integration status to your organization administrator or Mobius support; there is no organization setting that repairs Pub/Sub delivery.

Next

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