> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail

> Gmail REST API access for reading, composing, sending, and managing email on behalf of a connected user.

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

10 example endpoints available through Lava's AI Gateway. See the [Gmail API docs](https://developers.google.com/gmail/api/reference/rest) for full documentation.

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

<Info>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/\&#123;path\&#125](https://gmail.googleapis.com/gmail/v1/\&#123;path\&#125);. 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. To send or draft mail (messages.send or drafts.create), the simplest path is structured fields: pass `{ to, subject, body }` (plus optional `cc`, `bcc`) — `to`/`cc`/`bcc` may be a string or an array, `body` is plain text — and Lava builds and encodes the message for you (the body is delivered as HTML so it reflows in the reader's client). Advanced callers may instead set `raw` to a plaintext RFC 2822 message: Lava base64url-encodes it, so do NOT pre-encode, and use an HTML body to avoid the \~78-column hard-wrap a bare text/plain send suffers. See [https://developers.google.com/gmail/api/reference/rest](https://developers.google.com/gmail/api/reference/rest) for full reference. The endpoints below are curated examples.</Info>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/profile', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is%3Aunread&maxResults=10', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4?format=metadata&metadataHeaders=Subject&metadataHeaders=From', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"}'
    ```
  </Tab>
</Tabs>

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

**POST** `https://gmail.googleapis.com/gmail/v1/users/me/drafts` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"}}'
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/18e2f5d8b1a2c3d4/modify', { body: {"removeLabelIds":["UNREAD"]} });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"]}'
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/threads?q=from%3Aboss%40example.com&maxResults=5', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/threads/18e2f5d8b1a2c3d4', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/labels', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

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

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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/labels', {
      body: {
    "name": "Lava/Processed",
    "labelListVisibility": "labelShow",
    "messageListVisibility": "show"
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"}'
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="All Providers" icon="grid" href="/gateway/supported-providers">
    Browse all supported AI providers
  </Card>

  <Card title="Forward Proxy" icon="route" href="/gateway/forward-proxy">
    Learn how to construct proxy URLs and authenticate requests
  </Card>
</CardGroup>