Connect Gmail to your AI agent

Authentication methods

• OAuth 2.0

Open the local console, select a provider, and configure its credentials. OAuth providers require an OAuth app you register with that service.

What to check for this connector

This get_profile example reads mailbox identity and totals, not message bodies. Check emailAddress against the intended mailbox; messagesTotal and threadsTotal are counts, and historyId is a cursor. Confirm the required Gmail read scope before execution.

Inspect the Action before calling it

Example purpose

Read the connected Gmail mailbox profile and totals.

Required Action scopes

• https://www.googleapis.com/auth/gmail.readonly

Read the schema from your running instance. Check required input, permissions, and the account connection before execution.

curl -s http://localhost:3000/v1/actions/gmail.get_profile

After connecting an account, adapt the example input to your resources. Add a runtime bearer token if runtime authentication is enabled.

curl -s -X POST \
  http://localhost:3000/v1/actions/gmail.get_profile \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Read the result

HTTP runtime responses use success, message, data and meta. Inspect success and the Action’s output schema, not just the HTTP status. When execution metadata includes executionId, use it to find the corresponding redacted run log. The example below illustrates the envelope; it is not a live API result.

{
  "success": true,
  "message": "OK",
  "data": {
    "emailAddress": "reader@example.com",
    "messagesTotal": 12,
    "threadsTotal": 8,
    "historyId": "12345"
  },
  "meta": {}
}

If the call fails

• For an authentication failure, check the endpoint and credential type: admin access protects /api; a runtime bearer token authorizes /v1 and /mcp. A provider API key is not a runtime token.
• For a permission denial, check the Action’s required scopes, runtime Action rules and connection grants. A valid token may still be forbidden from using the selected account.
• For empty or missing results, confirm the connected account and its access to the requested resource. Successful authorization does not grant access to every workspace, channel or document.
• Inspect the error and run log before retrying. If an Action changes provider data, check whether it already completed; do not blindly repeat the request.

Next steps

For supported providers, OOMOL handles OAuth app configuration and the hosted runtime. You still choose the account and approve its permissions.