Gmail
Search and read messages, list and change labels, and send email
Connect Gmail when a project needs to work with one mailbox or each published app user's mailbox. Swarmz supports shared project and published app-user connections without exposing Google tokens to generated browser code.
Available operations
| Operation | What it does | Permission | Limit per minute |
|---|---|---|---|
search_messages | Searches one page of messages with a Gmail query and optional labels | Read email | 60 |
get_message | Reads one message in full, metadata, or minimal format | Read email | 60 |
list_labels | Lists labels in the mailbox | Read email | 60 |
modify_labels | Adds or removes labels on one message | Manage labels | 60 |
send_email | Sends one text, HTML, or multipart email | Send email | 60 |
Read email is selected by default. Sending email and changing labels are separate choices so a read-only app does not receive write access.
Connect Gmail
An administrator must first open Admin > Settings > Integrations, configure the Google OAuth app, and enable Gmail. Platform accounts configure their own Google OAuth app in the corresponding Platform integration settings.
In project chat, name the action and account owner. For example:
- “Search our support mailbox for unread refund requests.”
- “Send an order receipt from our shared Gmail account.”
- “Let every signed-in user connect Gmail and show their unread messages.”
Choose an existing connection or select Connect new, select only the permissions the feature needs, authorize the Google account, then continue the build. See Connector connection modes before choosing a shared or published app-user account.
Use Gmail in a published app
Ask the AI to use published app-user mode and provide the final HTTPS origin. Generated server handlers identify the signed-in app user, then call the Swarmz connector gateway. The browser never receives the Google access token or project gateway key.
For a mailbox view, start with search_messages, then call get_message only after the user selects a result. Reuse the returned page token for the next page. Do not repeatedly poll Gmail from the browser.
Verify Gmail
- Search for a message with a unique subject in a test mailbox.
- Read that message and confirm the sender, subject, and snippet.
- List labels and record one test label ID.
- If label access was approved, add the test label, confirm it in Gmail, then remove it.
- If send access was approved, send a message with a unique marker to a test address and confirm delivery.
If reads work but sending or label changes fail, reconnect and approve the missing permission. If authorization was revoked in Google, reconnect the same Swarmz connection. Disconnecting removes Swarmz access; it does not delete email or labels in Gmail.
Message bodies and addresses can contain personal data. Request the narrowest permission, keep provider calls in server routes, and avoid copying mailbox content into logs or analytics.