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 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. When composing mail (messages.send or drafts.create), set raw to the plaintext RFC 2822 message — Lava base64url-encodes it for you, so do NOT pre-encode — and use an HTML body (Content-Type: text/html): a bare text/plain body hard-wraps at ~78 columns on send and shows premature mid-sentence line breaks. See https://developers.google.com/gmail/api/reference/rest for full reference. The endpoints below are curated examples.
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. Set raw to the plaintext RFC 2822 message (To/Subject/… headers, a blank line, then the body) — Lava base64url-encodes it for you, so do NOT pre-encode. Send the body as HTML: set MIME-Version: 1.0 and Content-Type: text/html; charset="UTF-8", and use <p>/<br> for line structure. A bare text/plain body is hard-wrapped at ~78 columns on send — Gmail inserts physical line breaks to satisfy RFC 5322 line limits, which surface as premature mid-sentence breaks in the delivered mail. HTML reflows to the reader’s window and avoids this; multipart/alternative (plain + HTML) is the most compatible. The connected account must have send permission (Pipedream’s default Gmail scopes include gmail.send).
const data = await lava.gateway('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', { body: {"raw": "To: recipient@example.com\r\nSubject: Hello\r\nMIME-Version: 1.0\r\nContent-Type: text/html; charset=\"UTF-8\"\r\n\r\n<p>Hi there,</p><p>Sending this as HTML so the body reflows to the reader's window instead of hard-wrapping at ~78 columns.</p><p>Best,<br>Lava</p>"},});
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":"To: recipient@example.com\r\nSubject: Hello\r\nMIME-Version: 1.0\r\nContent-Type: text/html; charset=\"UTF-8\"\r\n\r\n<p>Hi there,</p><p>Sending this as HTML so the body reflows to the reader's window instead of hard-wrapping at ~78 columns.</p><p>Best,<br>Lava</p>"}'
Create a draft (does NOT send). Body is { "message": { "raw": <plaintext RFC 2822 message> } } — Lava base64url-encodes raw for you, so do NOT pre-encode. For a threaded reply, put threadId next to raw in message and include In-Reply-To and References headers (the original Message-ID, from messages.get) in the raw so Gmail threads it. Same HTML-body guidance as messages.send.
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.
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.
