Gmail - Lava Documentation

Gmail REST API access for reading, composing, sending, and managing email on behalf of a connected user. Use when an agent needs to read inbox state, draft and send messages, manage labels, or work with threads in a user’s Gmail account. Routes through Pipedream Connect — the user sees one Google consent screen on connect that says “Pipedream wants access” (Pipedream owns the verified OAuth client). Differs from raw SMTP because all calls go through the official Gmail REST API with full structured-data access (labels, threads, attachments metadata). 9 example endpoints available through Lava’s AI Gateway. See the Gmail API docs for full documentation.

This provider requires your own credentials — connect your API key or OAuth account before use.

This is a catch-all provider — any valid URL under https://gmail.googleapis.com is supported. Gmail REST API endpoints. Construct URLs as https://gmail.googleapis.com/gmail/v1/{path}. Authentication is brokered through Pipedream Connect — the end-user sees a single “Pipedream wants to access your Google Account” consent screen on connect. Common roots: users/me/profile, users/me/messages, users/me/threads, users/me/labels, users/me/drafts. See https://developers.google.com/gmail/api/reference/rest for full reference. The endpoints below are curated examples.

Endpoints

Get the connected Gmail account’s profile (email address, total messages count). Use this as a cheap auth probe after connect — confirms the OAuth grant is healthy without enumerating messages.

GET https://gmail.googleapis.com/gmail/v1/users/me/profile — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/profile', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fprofile" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

List messages in the user’s mailbox, optionally filtered by a Gmail search query (q param). Returns lightweight references — use messages.get to fetch full content. Supports labelIds, maxResults, pageToken.

GET https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is%3Aunread&maxResults=10 — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is%3Aunread&maxResults=10', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fmessages%3Fq%3Dis%253Aunread%26maxResults%3D10" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

GET

https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4?format=metadata&metadataHeaders=Subject&metadataHeaders=From

— Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4?format=metadata&metadataHeaders=Subject&metadataHeaders=From', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fmessages%2F18e2f5d8b1a2c3d4%3Fformat%3Dmetadata%26metadataHeaders%3DSubject%26metadataHeaders%3DFrom" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Send an email on behalf of the connected user. Body field “raw” is a URL-safe base64-encoded RFC 2822 message (including From/To/Subject/body headers). The connected account must have permission to send (Pipedream’s default Gmail scopes include gmail.send).

POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
  body: {
"raw": "VG86IHJlY2lwaWVudEBleGFtcGxlLmNvbQpTdWJqZWN0OiBIZWxsbwoKSGVsbG8gZnJvbSBMYXZhIQ"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fmessages%2Fsend" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"raw":"VG86IHJlY2lwaWVudEBleGFtcGxlLmNvbQpTdWJqZWN0OiBIZWxsbwoKSGVsbG8gZnJvbSBMYXZhIQ"}'

Add or remove labels on a message. Common use: mark as read by removing UNREAD; archive by removing INBOX; star by adding STARRED.

POST https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4/modify — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4/modify', { body: {"removeLabelIds":["UNREAD"]} });

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fmessages%2F18e2f5d8b1a2c3d4%2Fmodify" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"removeLabelIds":["UNREAD"]}'

List threads in the user’s mailbox. Threads bundle reply chains together — prefer threads.list over messages.list when an agent needs to reason about conversations rather than individual messages.

GET https://gmail.googleapis.com/gmail/v1/users/me/threads?q=from%3Aboss%40example.com&maxResults=5 — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/threads?q=from%3Aboss%40example.com&maxResults=5', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fthreads%3Fq%3Dfrom%253Aboss%2540example.com%26maxResults%3D5" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Get a full thread (all messages in the reply chain). Format options match messages.get: metadata for headers, full for bodies.

GET https://gmail.googleapis.com/gmail/v1/users/me/threads/18e2f5d8b1a2c3d4 — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/threads/18e2f5d8b1a2c3d4', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fthreads%2F18e2f5d8b1a2c3d4" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

List the user’s labels — both system labels (INBOX, UNREAD, STARRED, IMPORTANT, etc.) and any custom labels the user has created. Returns ID + name for each; agents need IDs (not names) for modify operations.

GET https://gmail.googleapis.com/gmail/v1/users/me/labels — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/labels', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Flabels" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

POST https://gmail.googleapis.com/gmail/v1/users/me/labels — Free

SDK
cURL

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/labels', {
  body: {
"name": "Lava/Processed",
"labelListVisibility": "labelShow",
"messageListVisibility": "show"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Flabels" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lava/Processed","labelListVisibility":"labelShow","messageListVisibility":"show"}'

Next Steps

All Providers

Browse all supported AI providers

Forward Proxy

Learn how to construct proxy URLs and authenticate requests

⌘I

Documentation Index

​Endpoints

​Get the connected Gmail account’s profile (email address, total messages count). Use this as a cheap auth probe after connect — confirms the OAuth grant is healthy without enumerating messages.

​List messages in the user’s mailbox, optionally filtered by a Gmail search query (q param). Returns lightweight references — use messages.get to fetch full content. Supports labelIds, maxResults, pageToken.

​Get a single message by id. Use format=metadata for cheap header-only reads, format=full for the complete body. Recommend format=metadata + metadataHeaders=Subject,From,To,Date for inbox triage workflows.

​Send an email on behalf of the connected user. Body field “raw” is a URL-safe base64-encoded RFC 2822 message (including From/To/Subject/body headers). The connected account must have permission to send (Pipedream’s default Gmail scopes include gmail.send).

​Add or remove labels on a message. Common use: mark as read by removing UNREAD; archive by removing INBOX; star by adding STARRED.

​List threads in the user’s mailbox. Threads bundle reply chains together — prefer threads.list over messages.list when an agent needs to reason about conversations rather than individual messages.

​Get a full thread (all messages in the reply chain). Format options match messages.get: metadata for headers, full for bodies.

​List the user’s labels — both system labels (INBOX, UNREAD, STARRED, IMPORTANT, etc.) and any custom labels the user has created. Returns ID + name for each; agents need IDs (not names) for modify operations.

​Create a new custom label. Required scope is included in Pipedream’s default Gmail consent. Set labelListVisibility and messageListVisibility to control where the label appears in the Gmail UI.

​Next Steps

All Providers

Forward Proxy

Endpoints

Get the connected Gmail account’s profile (email address, total messages count). Use this as a cheap auth probe after connect — confirms the OAuth grant is healthy without enumerating messages.

List messages in the user’s mailbox, optionally filtered by a Gmail search query (q param). Returns lightweight references — use messages.get to fetch full content. Supports labelIds, maxResults, pageToken.

Get a single message by id. Use format=metadata for cheap header-only reads, format=full for the complete body. Recommend format=metadata + metadataHeaders=Subject,From,To,Date for inbox triage workflows.

Send an email on behalf of the connected user. Body field “raw” is a URL-safe base64-encoded RFC 2822 message (including From/To/Subject/body headers). The connected account must have permission to send (Pipedream’s default Gmail scopes include gmail.send).

Add or remove labels on a message. Common use: mark as read by removing UNREAD; archive by removing INBOX; star by adding STARRED.

List threads in the user’s mailbox. Threads bundle reply chains together — prefer threads.list over messages.list when an agent needs to reason about conversations rather than individual messages.

Get a full thread (all messages in the reply chain). Format options match messages.get: metadata for headers, full for bodies.

List the user’s labels — both system labels (INBOX, UNREAD, STARRED, IMPORTANT, etc.) and any custom labels the user has created. Returns ID + name for each; agents need IDs (not names) for modify operations.

Create a new custom label. Required scope is included in Pipedream’s default Gmail consent. Set labelListVisibility and messageListVisibility to control where the label appears in the Gmail UI.

Next Steps