Clojure wrapper for the Gmail API (v1).
Provides idiomatic Clojure functions for reading, sending, and managing email in Gmail — messages, threads, labels, and drafts.
Auth: use csl/scoped-delegated-credentials or csl/user-credentials with the appropriate scope:
All functions take a user-id parameter (typically "me" for the authenticated user). Service accounts with domain-wide delegation may pass a user's email address instead.
Enum options (e.g. :format) accept kebab-case keywords that are coerced internally (:full -> "FULL", :message-added -> "MESSAGE_ADDED").
All list functions return {:data [...] :next-page-token "..."}; the caller is responsible for pagination by passing :page-token from one call to the next. :next-page-token is absent when there are no further pages.
All functions return {:data ...} on success or {:error ...} on failure.
Clojure wrapper for the Gmail API (v1).
Provides idiomatic Clojure functions for reading, sending, and managing
email in Gmail — messages, threads, labels, and drafts.
Auth: use csl/scoped-delegated-credentials or csl/user-credentials with
the appropriate scope:
- GmailScopes/GMAIL_READONLY (read-only access to messages and labels)
- GmailScopes/GMAIL_SEND (send messages only)
- GmailScopes/GMAIL_COMPOSE (create, read, update, and delete drafts; send)
- GmailScopes/GMAIL_MODIFY (all read/write except permanent delete)
- GmailScopes/GMAIL_LABELS (manage labels only)
- GmailScopes/MAIL_GOOGLE_COM (full access including permanent delete)
All functions take a user-id parameter (typically "me" for the
authenticated user). Service accounts with domain-wide delegation may
pass a user's email address instead.
Enum options (e.g. :format) accept kebab-case keywords that are coerced
internally (:full -> "FULL", :message-added -> "MESSAGE_ADDED").
All list functions return {:data [...] :next-page-token "..."}; the caller
is responsible for pagination by passing :page-token from one call to the next.
:next-page-token is absent when there are no further pages.
All functions return {:data ...} on success or {:error ...} on failure.(batch-delete-messages client user-id message-ids & [opts])Permanently delete multiple messages. NOT reversible.
message-ids — vector of message ID strings.
Permanently delete multiple messages. NOT reversible. message-ids — vector of message ID strings.
(batch-modify-messages client user-id message-ids modifications & [opts])Modify labels on multiple messages at once.
message-ids — vector of message ID strings modifications — map with :add-label-ids and/or :remove-label-ids.
Modify labels on multiple messages at once. message-ids — vector of message ID strings modifications — map with :add-label-ids and/or :remove-label-ids.
(create-draft client user-id message-data & [opts])Create a new draft.
message-data — follows the same format as send-message: a map with :to, :subject, :body (and optionally :from, :cc, :bcc, :content-type), or a map with :raw containing a pre-encoded base64url RFC 2822 string.
Create a new draft. message-data — follows the same format as send-message: a map with :to, :subject, :body (and optionally :from, :cc, :bcc, :content-type), or a map with :raw containing a pre-encoded base64url RFC 2822 string.
(create-label client user-id label-data & [opts])Create a new label.
label-data — map with :name (required), optionally :label-list-visibility (:label-show, :label-show-if-unread, :label-hide) and :message-list-visibility (:show, :hide).
Create a new label. label-data — map with :name (required), optionally :label-list-visibility (:label-show, :label-show-if-unread, :label-hide) and :message-list-visibility (:show, :hide).
(delete-draft client user-id draft-id & [opts])Delete a draft.
Delete a draft.
(delete-label client user-id label-id & [opts])Delete a label.
Delete a label.
(delete-message client user-id message-id & [opts])Permanently delete a message. This is NOT reversible; prefer trash-message.
Permanently delete a message. This is NOT reversible; prefer trash-message.
(delete-thread client user-id thread-id & [opts])Permanently delete a thread. NOT reversible.
Permanently delete a thread. NOT reversible.
(extract-body message mime-type)Extract the body content of a given MIME type from a message.
message — a message map as returned by get-message (with format :full) mime-type — string, e.g. "text/plain" or "text/html"
Returns the decoded body string, or nil if no matching part exists. Walks the payload parts tree for multipart messages.
Extract the body content of a given MIME type from a message. message — a message map as returned by get-message (with format :full) mime-type — string, e.g. "text/plain" or "text/html" Returns the decoded body string, or nil if no matching part exists. Walks the payload parts tree for multipart messages.
(extract-headers message)Extract headers from a message as a map of header-name string to value string.
Returns string keys (e.g. {"Subject" "Hello", "From" "alice@example.com"}) because email headers are case-sensitive per RFC 2822.
message — a message map as returned by get-message (with format :full or :metadata).
Extract headers from a message as a map of header-name string to value string.
Returns string keys (e.g. {"Subject" "Hello", "From" "alice@example.com"})
because email headers are case-sensitive per RFC 2822.
message — a message map as returned by get-message (with format :full
or :metadata).(get-auto-forwarding client user-id & [opts])Get the auto-forwarding configuration for the mailbox.
opts:
Get the auto-forwarding configuration for the mailbox. opts: - :fields — partial response field mask string
(get-draft client user-id draft-id & [opts])Get a draft by ID.
opts:
Get a draft by ID. opts: - :format — :full (default), :minimal, :raw, :metadata - :fields — partial response field mask string (e.g. "id,message(id,payload(headers))")
(get-imap client user-id & [opts])Get the IMAP settings for the mailbox.
opts:
Get the IMAP settings for the mailbox. opts: - :fields — partial response field mask string
(get-label client user-id label-id & [opts])Get a label by ID.
opts:
Get a label by ID. opts: - :fields —partial response field mask string.
(get-language client user-id & [opts])Get the display language preference for the mailbox.
opts:
Get the display language preference for the mailbox. opts: - :fields — partial response field mask string
(get-message client user-id message-id & [opts])Get a message by ID.
opts:
Get a message by ID. opts: - :format — :full (default), :minimal, :raw, :metadata - :metadata-headers — vector of header names (when format is :metadata) - :fields — partial response field mask string (e.g. "id,threadId,payload(headers,body)")
(get-pop client user-id & [opts])Get the POP settings for the mailbox.
opts:
Get the POP settings for the mailbox. opts: - :fields — partial response field mask string
(get-profile client user-id & [opts])Get the Gmail profile for a mailbox.
Returns email address, total message count, total thread count, and history id.
opts:
Get the Gmail profile for a mailbox. Returns email address, total message count, total thread count, and history id. opts: - :fields — partial response field mask string
(get-thread client user-id thread-id & [opts])Get a thread by ID.
opts:
Get a thread by ID. opts: - :format — :full (default), :minimal, :metadata - :metadata-headers — vector of header names (when format is :metadata) - :fields — partial response field mask string (e.g. "id,messages(id,payload(headers))")
(get-vacation client user-id & [opts])Get the vacation auto-reply configuration for the mailbox.
opts:
Get the vacation auto-reply configuration for the mailbox. opts: - :fields — partial response field mask string
(gmail-client credentials)(gmail-client credentials opts)Build an authenticated Gmail v1 REST client.
credentials — a com.google.auth.oauth2.GoogleCredentials instance, typically from csl/scoped-delegated-credentials or csl/user-credentials.
opts (optional):
Per-request opts on individual call sites override the client-level defaults.
Build an authenticated Gmail v1 REST client. credentials — a com.google.auth.oauth2.GoogleCredentials instance, typically from csl/scoped-delegated-credentials or csl/user-credentials. opts (optional): - :read-timeout-ms per-client default read timeout (default 120000 / 120s) - :connect-timeout-ms per-client default connect timeout (default 30000 / 30s) Per-request opts on individual call sites override the client-level defaults.
(list-delegates client user-id & [opts])List the mailbox delegates configured on the user's mailbox.
opts:
List the mailbox delegates configured on the user's mailbox. opts: - :fields — partial response field mask string
(list-drafts client user-id & [opts])List drafts.
opts:
List drafts. opts: - :q — Gmail search query string - :page-token — token from a previous response - :page-size — max results per page - :fields — partial response field mask string (e.g. "drafts(id,message(id,threadId)),nextPageToken")
(list-filters client user-id & [opts])List the message filters configured on the mailbox.
The Gmail response array field for this endpoint is named filter
(singular) — Google's choice. Items therefore surface under
:filter (singular) in the response, not :filters.
opts:
List the message filters configured on the mailbox. The Gmail response array field for this endpoint is named `filter` (singular) — Google's choice. Items therefore surface under `:filter` (singular) in the response, not `:filters`. opts: - :fields — partial response field mask string
(list-forwarding-addresses client user-id & [opts])List the forwarding addresses configured on the mailbox.
opts:
List the forwarding addresses configured on the mailbox. opts: - :fields — partial response field mask string
(list-history client user-id start-history-id & [opts])List history records after a given historyId for incremental sync.
start-history-id — the historyId to start from (obtained from a previous message/thread get or list-history response)
opts:
Returns {:data [...] :history-id "..." :next-page-token "..."}. :history-id is the latest history record on the mailbox; persist it as the next sync watermark. :next-page-token is absent on the last page.
List history records after a given historyId for incremental sync.
start-history-id — the historyId to start from (obtained from a previous
message/thread get or list-history response)
opts:
- :label-id — only return history for this label
- :history-types — vector of types to include: :message-added,
:message-deleted, :label-added, :label-removed
- :page-token — token from a previous response
- :page-size — max results per page
- :fields — partial response field mask string (e.g.
"history(id,messagesAdded),historyId,nextPageToken")
Returns {:data [...] :history-id "..." :next-page-token "..."}.
:history-id is the latest history record on the mailbox; persist it as
the next sync watermark. :next-page-token is absent on the last page.(list-labels client user-id & [opts])List all labels for the user's mailbox.
opts:
List all labels for the user's mailbox. opts: - :fields —partial response field mask string (e.g. "labels(id,name)").
(list-messages client user-id & [opts])List messages matching a query.
opts:
List messages matching a query. opts: - :q — Gmail search query string (same as web UI search box) - :label-ids — vector of label ID strings to filter by - :page-token — token from a previous response - :page-size — max results per page (default 100, max 500) - :fields — partial response field mask string (e.g. "messages(id,threadId),nextPageToken")
(list-send-as client user-id & [opts])List the Send-As aliases configured on the mailbox.
opts:
List the Send-As aliases configured on the mailbox. opts: - :fields — partial response field mask string
(list-threads client user-id & [opts])List threads matching a query.
opts:
List threads matching a query. opts: - :q — Gmail search query string - :label-ids — vector of label ID strings - :page-token — token from a previous response - :page-size — max results per page - :fields — partial response field mask string (e.g. "threads(id,historyId),nextPageToken")
(modify-message client user-id message-id modifications & [opts])Modify label assignments on a message.
modifications — map with :add-label-ids and/or :remove-label-ids (vectors of label ID strings).
Modify label assignments on a message. modifications — map with :add-label-ids and/or :remove-label-ids (vectors of label ID strings).
(modify-thread client user-id thread-id modifications & [opts])Modify label assignments on an entire thread.
modifications — map with :add-label-ids and/or :remove-label-ids.
Modify label assignments on an entire thread. modifications — map with :add-label-ids and/or :remove-label-ids.
(send-draft client user-id draft-id & [opts])Send an existing draft.
Send an existing draft.
(send-message client user-id message-data & [opts])Send a message. Accepts either:
For thread replies, include :thread-id in the map.
The convenience form handles simple text and HTML messages. For complex MIME (attachments, multipart/mixed, inline images) or non-ASCII subject lines that require RFC 2047 encoding, provide a pre-encoded :raw string.
Send a message. Accepts either:
- A map with :to, :subject, :body (plain text), and optionally :from,
:cc, :bcc, :content-type ("text/html" for HTML)
- A map with :raw containing a pre-encoded base64url RFC 2822 string
For thread replies, include :thread-id in the map.
The convenience form handles simple text and HTML messages. For complex
MIME (attachments, multipart/mixed, inline images) or non-ASCII subject
lines that require RFC 2047 encoding, provide a pre-encoded :raw string.(trash-message client user-id message-id & [opts])Move a message to trash.
Move a message to trash.
(trash-thread client user-id thread-id & [opts])Move an entire thread to trash.
Move an entire thread to trash.
(untrash-message client user-id message-id & [opts])Remove a message from trash.
Remove a message from trash.
(untrash-thread client user-id thread-id & [opts])Remove a thread from trash.
Remove a thread from trash.
(update-draft client user-id draft-id message-data & [opts])Replace the content of a draft.
message-data — follows the same format as send-message.
Replace the content of a draft. message-data — follows the same format as send-message.
(update-label client user-id label-id label-data & [opts])Update a label's properties.
label-data — map with fields to update (:name, :label-list-visibility, etc.)
Update a label's properties. label-data — map with fields to update (:name, :label-list-visibility, etc.)
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |