Gmail

Gmail Integration

GmailService → GmailAdapter → Google Gmail API v1

Google OAuth 2.0 · 23 actions · Threads · Messages · Labels · Attachments

Service Layer

GmailService

Action routing
Param validation
Error handling

→

calls

Adapter

GmailAdapter

HTTP client
OAuth token injection
RFC 2822 parsing

→

REST

External API

Google Gmail API

REST v1
googleapis.com
Bearer token auth

OAuth Scope Breakdown

gmail.readonly

Read threads, messages, labels

gmail.send

Send emails & drafts

gmail.modify

Trash, label, unlabel

gmail.labels

Create, update, delete labels

What is the Gmail Integration?

The Gmail integration gives Octopus full programmatic access to Google Gmail via the Gmail REST API v1. It covers the entire email lifecycle: reading and searching messages, managing threads, composing and sending email, working with drafts, organizing with labels, and downloading attachments.

Authentication uses Google OAuth 2.0 with granular scope control — only the permissions your workflow actually needs are requested at authorization time.

Key capabilities:

• Thread & message management — list, search, get, trash, and delete conversations
• Send & reply — compose new emails, reply to threads, forward messages
• Drafts — create, list, and send drafts programmatically
• Label organization — full CRUD for labels plus apply/remove on messages and threads
• Attachments — list and download file attachments from messages
• RFC 2822 raw headers — access raw Internet Message Format headers for advanced parsing

---

Gmail Data Model

Thread → Messages → Labels · Attachments

Thread

threadId (stable)

id — string — Gmail thread ID

snippet — First message preview

historyId — Change tracking cursor

↓

contains one or more

Message

messageId (unique per message)

id — message ID

threadId — parent thread

labelIds — applied labels

payload — MIME body + headers

internalDate — received timestamp

raw — RFC 2822 bytes (opt)

↓

Labels

System: INBOX, SENT, TRASH, SPAM, DRAFT, UNREAD, STARRED

Custom: user-defined, color-coded

↓

Attachments

Part of MIME payload tree

Referenced by attachmentId

Fetched separately via get_attachment

Pass --include-headers to get_message to receive the full RFC 2822 raw header block for advanced email parsing.

Methods Reference

All 23 available actions with descriptions and key parameters.

Threads

Method	Description	Key Parameters
list_threads	List threads in mailbox with optional filter	query, maxResults, pageToken, labelIds
get_thread	Fetch full thread with all messages	thread_id, format (full | metadata | minimal)
trash_thread	Move thread to Trash	thread_id
delete_thread	Permanently delete thread (irreversible)	thread_id
modify_thread	Add or remove labels on all thread messages	thread_id, addLabelIds, removeLabelIds

Messages

Method	Description	Key Parameters
list_messages	List message IDs in mailbox	query, maxResults, pageToken, labelIds
search_messages	Search messages using Gmail query syntax	query (e.g. from:boss@company.com is:unread)
get_message	Fetch a single message by ID	message_id, format, --include-headers (raw RFC 2822)

Drafts

Method	Description	Key Parameters
create_draft	Create a new draft	to, subject, body, cc, bcc
list_drafts	List all drafts in the account	maxResults, pageToken
send_draft	Send an existing draft	draft_id

Send

Method	Description	Key Parameters
send_email	Compose and send a new email	to, subject, body, cc, bcc, reply_to
reply_to_thread	Reply to an existing thread	thread_id, body, to, cc
forward_message	Forward a message to new recipients	message_id, to, body

Labels

Method	Description	Key Parameters
list_labels	List all labels (system + custom)	—
create_label	Create a new custom label	name, messageListVisibility, labelListVisibility, color
update_label	Update an existing label's name or color	label_id, name, color
delete_label	Delete a custom label	label_id

Label Operations

Method	Description	Key Parameters
label_message	Apply one or more labels to a message	message_id, label_ids
unlabel_message	Remove one or more labels from a message	message_id, label_ids
label_thread	Apply labels to all messages in a thread	thread_id, label_ids
unlabel_thread	Remove labels from all messages in a thread	thread_id, label_ids

Attachments

Method	Description	Key Parameters
list_attachments	List all attachments on a message	message_id
get_attachment	Download attachment data by ID	message_id, attachment_id

---

CLI Reference

# Search for unread messages from a specific sender
constellation gmail search-messages --query "from:boss@company.com is:unread"

# Get a message with full raw RFC 2822 headers
constellation gmail get-message --message-id 18c3a9f2b8e12345 --include-headers

# List all threads in INBOX
constellation gmail list-threads --query "in:inbox" --max-results 20

# Send a new email
constellation gmail send-email \
  --to user@example.com \
  --subject "Hello from Octopus" \
  --body "Automated message via Constellation."

# Reply to an existing thread
constellation gmail reply-to-thread \
  --thread-id 18c3a9f2b8e12345 \
  --body "Thanks, got it."

# Create a draft
constellation gmail create-draft \
  --to user@example.com \
  --subject "Draft subject" \
  --body "Draft body content."

# Send an existing draft
constellation gmail send-draft --draft-id r8765432abcdef

# Create a custom label with color
constellation gmail create-label --name "Urgent" --color red

# Apply a label to a message
constellation gmail label-message \
  --message-id 18c3a9f2b8e12345 \
  --label-ids Label_12345

# Trash a thread
constellation gmail trash-thread --thread-id 18c3a9f2b8e12345

# List attachments on a message
constellation gmail list-attachments --message-id 18c3a9f2b8e12345

# Download an attachment
constellation gmail get-attachment \
  --message-id 18c3a9f2b8e12345 \
  --attachment-id ANGjdJ9qR3JVwE...

---

OAuth Scopes

Google OAuth 2.0 scopes are requested at authorization time. Only the scopes your workflow needs should be requested.

Scope	Full URI	What It Enables
gmail.readonly	https://www.googleapis.com/auth/gmail.readonly	Read all threads, messages, labels, and drafts. No write access.
gmail.send	https://www.googleapis.com/auth/gmail.send	Send email and send existing drafts.
gmail.modify	https://www.googleapis.com/auth/gmail.modify	All read + modify actions: trash, label/unlabel messages and threads. Does not grant permanent delete.
gmail.labels	https://www.googleapis.com/auth/gmail.labels	Create, update, and delete custom labels.

Least-privilege guidance: For read-only pipelines use gmail.readonly only. Add gmail.send only for outbound flows. gmail.modify is required for any label or trash operations. gmail.labels is only needed when managing the label taxonomy itself.

---

Error Handling

Error	Cause	Resolution
401 Unauthorized	Expired or revoked OAuth token	Re-authorize the integration via the OAuth flow
403 Forbidden	Action requires a scope not granted	Re-authorize with the required scope
404 Not Found	Message ID, thread ID, or attachment ID does not exist	Verify IDs with a list call first
429 Too Many Requests	Gmail API quota exceeded	Implement exponential backoff; check Google Cloud Console quotas
400 Bad Request	Invalid query syntax or missing required field	Check Gmail search syntax and required params