Gmail API integration with managed OAuth. Read, send, and manage emails, threads, labels, and drafts. Use this skill when users want to interact with Gmail. For other third party apps, use the api-gat
Real data. Real impact.
Emerging
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
Access the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.
# List messages python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
https://gateway.maton.ai/google-mail/{native-api-path}
Replace {native-api-path} with the actual Gmail API endpoint path. The gateway proxies requests to gmail.googleapis.com and automatically injects your OAuth token.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEY
Environment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"
Manage your Google OAuth connections at https://ctrl.maton.ai.
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-mail'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
Response:
{ "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-mail", "metadata": {} } }
Open the returned url in a browser to complete OAuth authorization.
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
If you have multiple Gmail connections, specify which one to use with the Maton-Connection header:
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
If omitted, the gateway uses the default (oldest) active connection.
GET /google-mail/gmail/v1/users/me/messages?maxResults=10
With query filter:
GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10
GET /google-mail/gmail/v1/users/me/messages/{messageId}
With metadata only:
GET /google-mail/gmail/v1/users/me/messages/{messageId}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date
POST /google-mail/gmail/v1/users/me/messages/send Content-Type: application/json { "raw": "BASE64_ENCODED_EMAIL" }
GET /google-mail/gmail/v1/users/me/labels
GET /google-mail/gmail/v1/users/me/threads?maxResults=10
GET /google-mail/gmail/v1/users/me/threads/{threadId}
POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify Content-Type: application/json { "addLabelIds": ["STARRED"], "removeLabelIds": ["UNREAD"] }
POST /google-mail/gmail/v1/users/me/messages/{messageId}/trash
POST /google-mail/gmail/v1/users/me/drafts Content-Type: application/json { "message": { "raw": "BASE64URL_ENCODED_EMAIL" } }
POST /google-mail/gmail/v1/users/me/drafts/send Content-Type: application/json { "id": "{draftId}" }
GET /google-mail/gmail/v1/users/me/profile
Use in the q parameter:
const response = await fetch( 'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } );
import os import requests response = requests.get( 'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'maxResults': 10, 'q': 'is:unread'} )
| Status | Meaning |
|---|---|
| 400 | Missing Gmail connection |
| 401 | Invalid or missing Maton API key |
| 429 | Rate limited (10 req/sec per account) |
| 4xx/5xx | Passthrough error from Gmail API |
echo $MATON_API_KEY
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
Ensure your URL path starts with google-mail. For example:
Correct: https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
Incorrect: https://gateway.maton.ai/gmail/v1/users/me/messages
MIT-0 (Free to use, modify, and redistribute. No a
No automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.