Connect EMQX Agents to Gmail

The Gmail connector lets EMQX Agents read, search, send, reply to, forward, and organize Gmail messages. It also supports drafts, attachments, labels, contacts, and account profile information.

Common Use Cases

• Summarize new support emails and classify them by label.
• Draft or send an alert email after an MQTT or Fleets event.
• Search a mail thread and use its context in an agent decision.
• Create a response draft for human review.

Example chat prompt:

Use the support-gmail connector to find unread messages with the label support, summarize each thread, and create reply drafts. Do not send the drafts.

Prerequisites

Before adding the connector, prepare:

• A Google account with Gmail enabled.
• Access to the account's sign-in and identity verification methods.
• Permission to authorize EMQX Agents to access the required Gmail data and actions.
• Access to any contacts, labels, threads, or messages required by the workflow.

Add a Gmail Connector

1. In the left navigation menu, click Connectors.
2. On the Available tab, locate Gmail and click Add.
3. Enter a descriptive connector name.
4. Click Confirm. EMQX Agents opens the Google authorization flow in a dialog.
5. Select the Google account that the connector should use, or sign in with another account.
6. Complete any additional identity verification requested by Google.
7. Review the basic account information that Google will share with Composio, and click Continue.
8. Review the additional permissions requested by Composio. Select the permissions required by the connector tools that you plan to use. These permissions can include:
   • Reading, composing, sending, and permanently deleting Gmail messages.
   • Viewing email addresses and Google Account profile information.
   • Viewing contacts and other contact information.
9. To allow Composio to retain access to the Google Account data that you authorize, select the continuous access option. If you do not select this option, Google requires you to review the access again every 6 months.
10. Click Continue to grant the selected permissions.
11. Wait for Composio to confirm that the connection succeeded and return you to EMQX Agents.
12. On the Added tab, verify that an Authorization successful message appears and that the connector status is Authorized.

Google can display different permissions depending on the account and the connector tools. Grant only the permissions required by the workflow. Google Workspace administrator policies can restrict authorization of third-party applications.

Supported Tools

Send and Draft Messages

Tool	Access	Description
GMAIL_SEND_EMAIL	Write	Sends an email from the authorized Gmail account.
GMAIL_REPLY_TO_THREAD	Write	Replies to a Gmail thread.
GMAIL_FORWARD_MESSAGE	Write	Forwards a Gmail message to one or more recipients.
GMAIL_CREATE_EMAIL_DRAFT	Write	Creates an email draft with recipients, subject, body, or attachments.

Read Messages and Threads

Tool	Access	Description
GMAIL_FETCH_EMAILS	Read	Fetches messages by label or Gmail search query.
GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	Read	Gets a message by message ID.
GMAIL_FETCH_MESSAGE_BY_THREAD_ID	Read	Gets messages in a thread by thread ID.
GMAIL_LIST_THREADS	Read	Lists Gmail threads.
GMAIL_GET_ATTACHMENT	Read	Gets an attachment from a Gmail message.

Labels and Trash

Tool	Access	Description
GMAIL_ADD_LABEL_TO_EMAIL	Write	Adds or removes labels on a message.
GMAIL_CREATE_LABEL	Write	Creates a Gmail label.
GMAIL_LIST_LABELS	Read	Lists Gmail labels.
GMAIL_MOVE_TO_TRASH	Destructive	Moves a message to trash.
GMAIL_MOVE_THREAD_TO_TRASH	Destructive	Moves a thread to trash.
GMAIL_UNTRASH_MESSAGE	Write	Restores a message from trash.
GMAIL_UNTRASH_THREAD	Write	Restores a thread from trash.
GMAIL_MODIFY_THREAD_LABELS	Write	Adds or removes labels on a thread.
GMAIL_BATCH_MODIFY_MESSAGES	Write	Adds or removes labels on multiple messages.

Manage Drafts

Tool	Access	Description
GMAIL_LIST_DRAFTS	Read	Lists drafts in the authorized Gmail account.
GMAIL_GET_DRAFT	Read	Gets a draft.
GMAIL_UPDATE_DRAFT	Write	Updates a draft.
GMAIL_SEND_DRAFT	Write	Sends a draft.
GMAIL_DELETE_DRAFT	Destructive	Deletes a draft.

Contacts and Account

Tool	Access	Description
GMAIL_GET_CONTACTS	Read	Gets contacts from the authorized Google account.
GMAIL_SEARCH_PEOPLE	Read	Searches Google contacts and people by name, email, phone number, or organization.
GMAIL_GET_PROFILE	Read	Gets the Gmail account address and mailbox statistics.

Important Notice

Sending, replying to, or forwarding email communicates externally. Trash and bulk modification tools change mailbox data. Use drafts when human review is required.

Use the Connector in a Chat

1. In the chat input area, click the connector icon.
2. Select the authorized Gmail connector.
3. In the prompt, identify the external resource and operation that the agent should use.
4. Review the generated agent definition and confirm that it contains only the required tools.

Permissions and Data Access

The connector acts through the authorized Google account. The account's Gmail data, labels, contacts, and organization policies determine what the connector can access.

Do not include external service credentials or access tokens in the chat prompt or agent instructions.

Limitations

• Gmail API quotas and Google Workspace administrator policies apply.
• Attachment access depends on the message and account permissions.
• Sending, forwarding, trashing, and bulk label operations change the mailbox or communicate with external recipients.

Troubleshooting

Symptom	Resolution
The connector remains Unauthorized.	Retry authorization, complete any Google identity verification, and grant the required permissions. For a managed Google Workspace account, verify that the administrator allows access to Composio.
A tool returns a permission error.	Verify that the authorized account has access to the target resource and that the required Google permission was selected during authorization. Reauthorize the connector if needed.
A required tool is unavailable.	Verify that the tool is supported and approved for this connector, then select the connector again in the chat.
Requests are rejected intermittently.	Check the external service status, API quota, rate limits, and account plan.

Related Links

• Connectors
• Start a Chat
• Manage Agents