Gmail

​

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.

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.

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 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.

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. Simplest: pass structured fields — to (string or array of addresses), subject, and body (plain text; Lava delivers it as HTML so it reflows instead of hard-wrapping), plus optional cc/bcc. Lava assembles the RFC 2822 message and base64url-encodes it for you — no MIME or base64 by hand. Advanced: instead set raw to a plaintext RFC 2822 message (headers, blank line, body) and Lava encodes that; do NOT pre-encode. The connected account has send permission via Pipedream’s default Gmail scopes (gmail.send).

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
  body: {
"to": "recipient@example.com",
"subject": "Hello",
"body": "Hi there,\n\nSending this through Lava with structured fields — no MIME or base64 needed.\n\nBest,\nLava"
},
});

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 '{"to":"recipient@example.com","subject":"Hello","body":"Hi there,\n\nSending this through Lava with structured fields — no MIME or base64 needed.\n\nBest,\nLava"}'

​

Create a draft (does NOT send). Simplest: { "message": { "to": ..., "subject": ..., "body": ... } } — the same structured fields as messages.send (string or array addresses, plain-text body); Lava builds and encodes the message. For a threaded reply, add threadId next to the fields in message and pass inReplyTo/references (the original Message-ID from messages.get) so Gmail threads it. Advanced: instead set message.raw to a plaintext RFC 2822 message; do NOT pre-encode.

const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/drafts', {
  body: {
"message": {
  "to": "recipient@example.com",
  "subject": "Hello",
  "body": "Hi there,\n\nThis is a draft for review.\n\nBest,\nLava"
}
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgmail.googleapis.com%2Fgmail%2Fv1%2Fusers%2Fme%2Fdrafts" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":{"to":"recipient@example.com","subject":"Hello","body":"Hi there,\n\nThis is a draft for review.\n\nBest,\nLava"}}'

​

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

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.

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.

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.

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"

​

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.

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