Gmail

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

Use Gmail when an assistant 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.

The OAuth connection finishes in Mobius for the person who started it. Returning the browser to an embedded product is currently unavailable: a connect request that includes return_url is refused with 400 embedded_return_disabled.

Manage the mailbox and grant access

For Google sign-in, the account choice defaults to My account. An organization administrator can choose Shared account before starting OAuth for a mailbox the team shares, such as support@. Either choice represents the Google account selected on Google's screen. Mobius refuses to make a team member's own mailbox a shared account: if the address belongs to someone in your organization, connect it as their account instead.

A Workspace service-account key is a business credential. It is always team-managed, requires organization administration, and cannot be connected as a personal account. In the app, use Connect with a service account, paste the Service account JSON, and optionally name the Workspace mailbox the service account should act as. That mailbox can't be a team member's own address.

Connecting the mailbox does not give an assistant access. Open the connected account, find Assistant access, and add selected assistants. A personal grant limits use of the mailbox and retention of its tool results to the manager's Mobius audience. A team-managed mailbox can be available to the team or to named people. This result audience does not restrict the recipients of an outbound email.

If an assistant has several Gmail accounts, name the mailbox in the request or save an Account preferences choice for Your chats or Channel replies. Routines keep the exact Gmail accounts selected in their setup. Mobius does not fall back to another mailbox.

See Connect accounts for the full access flow.

Permissions

OAuth mode requests gmail.modify plus the connected account email. gmail.modify covers reading, drafts, sending, and label changes, and Google classifies it 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.attachment.get
gmail.attachment.list
gmail.attachment.save
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

gmail.message.list returns at most 50 messages per call, and 25 unless you ask for more. Each item has the IDs, sender, recipients, subject, date, labels, and a one-line snippet. Its email object carries only the trust fields: from_name, security.origin, security.prompt_boundary, security.injection_signals, and auth.sender_authenticated. A next_page_token means more messages match; pass it as page_token to read them.

gmail.thread.get returns each message's text once, in email.text and email.html_text, without the raw HTML. Use gmail.message.get when the assistant needs a message's original body and body_html. Use draft creation when a human should review mail before it is sent.

Attachments

gmail.message.get lists each attachment with its attachment_id, file name, media type, and size. gmail.attachment.list returns the same list on its own. Attachment IDs belong to the message they were listed under, so always pass the two together.

gmail.attachment.get reads one attachment inside the turn. Text attachments such as CSV, JSON, and plain text come back decoded in text. Other files come back as base64 content, bounded by max_bytes with a default of 256 KiB and a ceiling of 1 MiB, and truncated says when the file was longer. Base64 is rarely what an assistant wants for a PDF or spreadsheet.

gmail.attachment.save downloads one attachment and stores it in the Mobius library as a retained copy. The result carries the artifact_id. For PDF, DOCX, XLSX, and PPTX files, document_readable is true and the assistant can call mobius.document.inspect, mobius.document.read, and mobius.document.search on that ID to work with the content. Other files are available through mobius.file.read and the library page. Saving is bounded at 25 MiB, which is Gmail's own attachment limit.

Personal connections default to private; team-managed connections default to organization. Explicit visibility must fit the connection grant's audience. Saving the same attachment with the same visibility and effective custody (the same person or team) returns the existing file with existing: true. Deleting that copy allows a new save. The library details show the source message and saved time. Disconnecting Gmail does not delete saved copies.

Before sending, replying, archiving, trashing, or making another Gmail change, Mobius rechecks the resolved mailbox connection and live assistant grant. These actions run without an automatic Mobius confirmation. Creating a draft is useful when a person should review the message in Gmail 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 capped and neutralized before an assistant 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.message.get and gmail.thread.get return the same canonical email object; list items carry only its trust fields.

When the message carries attachments, the payload's has_attachment is exact and attachments lists each one with its attachment_id, filename, content_type, size, and is_inline. The same facts appear under event.email.attachments without the IDs. Attachment bytes are never on the event; use gmail.attachment.save or gmail.attachment.get in the turn. Assistant 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.
• Review dispatch and human-review boundaries in actions.
• Manage mailbox access in Connect accounts.
• Store finished files as artifacts.