Skip to Content
IntegrationsGoogle Mail

Google Mail

Connect a Gmail mailbox to send and draft email, search and read messages, and tidy your inbox. metamorphOS works against the connected account’s own mailbox, so every action happens as that user.

What you can do

  • Send mail: send an email with a rich-text or HTML body and optional file attachments to one or more recipients.
  • Drafts: save an unsent draft, with the same rich body and attachments.
  • Search and read: list messages, optionally narrowed by a Gmail search query or by label, and open a single message to read its contents.
  • Labels: add or remove labels on a message to mark it read, archive it, or star it.
  • Trash: move a message to the trash (restorable until Gmail empties it).

Before you start

You need a Google account with permission to create a project in the Google Cloud Console, or admin rights on an existing one. If your organisation uses Google Workspace, you also need to be able to configure the OAuth consent screen for the mailbox you want to connect.

Set up Google Mail

All provider-side setup happens in the Google Cloud Console (https://console.cloud.google.com ).

  1. Create or select a project. Open the project picker in the top bar and either pick an existing project or choose New Project, name it (for example, metamorphOS), and create it.
  2. Enable the Gmail API. Go to APIs & Services → Library, search for Gmail API, open it, and click Enable.
  3. Configure the OAuth consent screen. Go to APIs & Services → OAuth consent screen. Pick the user type (Internal if your Google Workspace org covers all users, otherwise External), fill in the app name, user support email, and developer contact email, and save. While the app is in Testing, add the mailbox accounts you will connect as Test users. Publish the app when you are ready for non-test users.
  4. Grant the mailbox permissions. On the consent screen’s Scopes (or Data Access) step, grant this connector permission to send email, compose drafts, read messages, and modify labels. These are sensitive Gmail permissions: for an External, published app, Google requires app verification (and a security assessment) before non-test users can grant them. Internal apps and test users are exempt.
  5. Create OAuth client credentials. Go to APIs & Services → Credentials → Create credentials → OAuth client ID, choose the Web application type, and name it. Google issues a Client ID and Client secret: copy both.
  6. Add the redirect URL. On that same OAuth client, under Authorized redirect URIs, add the callback URL metamorphOS provides for this connector. It must match exactly, including scheme and path. Save.

Connect in metamorphOS

Activate the Google Mail connector from the marketplace and add an account. Enter the Client ID and Client secret from the step above, then run the connect flow: metamorphOS opens Google’s consent page, where you sign in as the mailbox account and grant the requested permissions. Google redirects back to complete the connection, and the account is then ready to use. You can revoke the connection at any time to end metamorphOS’s access to that mailbox.

Good to know

  • The connector reads and writes only the connected user’s own mailbox.
  • It can move a message to the trash but cannot permanently delete one. Labels are edited per message: creating or deleting labels, thread-level actions, filters, and mailbox settings are not covered.
  • The connector acts on demand and does not receive inbound notifications, so it cannot yet trigger a process automatically when new mail arrives.
  • Field coverage is still expanding, so some advanced options may not be available yet.
Last updated on
Google GeminiGrafana