Gmail

Gmail API integration for automated email management in Axellero Workflow Designer and Agentflow Designer.

Setup Required: See the Setup Guide for authentication configuration and connector setup.

Setup Guide

Step-by-step authentication and connector configuration

The Gmail node enables comprehensive automation of email operations including sending and receiving messages, managing inbox organization, working with labels and threads, and monitoring mailbox changes in real-time through Pub/Sub triggers.

Key Features:

Send & Receive - Send emails with attachments, read and process incoming messages with full content access
Organize - Manage labels, threads, and drafts for inbox organization
Automate - Trigger workflows on new emails via Google Cloud Pub/Sub integration
Bulk Operations - Batch modify or delete multiple messages efficiently
Full Access - Access message headers, body (plain/HTML), and attachments

Connection Configuration

Parameter	Type	Required	Description
accessToken	TEXT	Yes	OAuth 2.0 access token for Gmail API authentication

Setup Instructions: See the Setup Guide for authentication configuration, connector creation, and getting started.

Available Operations

Category	Operation	Description
Profile & History	getProfile	Get user's email address and mailbox statistics
Profile & History	listHistory	List changes to the mailbox since a specific point
Messages	listMessages	List messages with optional search filtering
Messages	getMessage	Get a specific message with full content
Messages	sendMessage	Send an email with optional attachments
Messages	trashMessage	Move a message to trash
Messages	untrashMessage	Restore a message from trash
Messages	deleteMessage	Permanently delete a message
Messages	modifyMessage	Add or remove labels from a message
Messages	batchModifyMessages	Modify labels on multiple messages
Messages	batchDeleteMessages	Permanently delete multiple messages
Messages	getAttachment	Download an attachment from a message
Labels	listLabels	List all labels in the mailbox
Labels	getLabel	Get details of a specific label
Labels	createLabel	Create a new label
Labels	updateLabel	Update label properties
Labels	deleteLabel	Delete a label
Threads	listThreads	List conversation threads
Threads	getThread	Get a thread with all its messages
Threads	trashThread	Move a thread to trash
Threads	untrashThread	Restore a thread from trash
Threads	deleteThread	Permanently delete a thread
Threads	modifyThread	Add or remove labels from a thread
Drafts	listDrafts	List draft messages
Drafts	getDraft	Get a specific draft
Drafts	createDraft	Create a new draft
Drafts	updateDraft	Update an existing draft
Drafts	deleteDraft	Delete a draft
Drafts	sendDraft	Send a draft as an email

Operations Reference

Profile & History

getProfile

Get the user's Gmail profile including email address and mailbox statistics.

Parameters:

No additional parameters required.

Configuration Example:

{}

Note: Connector options (like accessToken) are automatically injected by the runtime. You only need to specify operation-specific parameters.

Success Response:

{
  "success": true,
  "data": {
    "emailAddress": "user@gmail.com",
    "messagesTotal": 15420,
    "threadsTotal": 8234,
    "historyId": "12345678"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

listHistory

List the history of changes to the mailbox since a specific point.

Parameters:

Parameter	Type	Required	Description
startHistoryId	TEXT	Yes	History ID to start from (from getProfile)
maxResults	INT	No	Maximum number of records (1-500)
pageToken	TEXT	No	Page token for pagination
labelId	TEXT	No	Filter history by this label
historyTypes	TEXT	No	Types: messageAdded, messageDeleted, labelAdded, labelRemoved

Configuration Example:

{
  "startHistoryId": "{{ctx.vars.lastHistoryId}}",
  "historyTypes": "messageAdded,labelAdded"
}

Success Response:

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "12345679",
        "messagesAdded": [
          {"message": {"id": "msg_abc123", "threadId": "thread_xyz789"}}
        ]
      }
    ],
    "historyId": "12345680",
    "nextPageToken": "token123"
  }
}

Messages

listMessages

List messages in the user's mailbox with optional filtering by search query and labels.

Parameters:

Parameter	Type	Required	Description
maxResults	INT	No	Maximum number of messages (1-500, default 100)
q	TEXT	No	Gmail search query (e.g., 'from:sender@example.com is:unread')
labelIds	TEXT	No	Comma-separated label IDs to filter by
pageToken	TEXT	No	Page token for pagination
includeSpamTrash	BOOLEAN	No	Include SPAM and TRASH messages

Configuration Example:

{
  "maxResults": 10,
  "q": "is:unread from:{{ctx.vars.senderEmail}}",
  "labelIds": "INBOX"
}

Success Response:

{
  "success": true,
  "data": {
    "messages": [
      {"id": "msg_abc123", "threadId": "thread_xyz789"},
      {"id": "msg_def456", "threadId": "thread_xyz789"}
    ],
    "nextPageToken": "token123",
    "resultSizeEstimate": 42
  }
}

getMessage

Get a specific message by ID with full content including headers, body, and attachments.

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message to retrieve
format	TEXT	No	Format: 'full', 'metadata', 'minimal', 'raw' (default: 'full')
metadataHeaders	TEXT	No	Headers to include when format is 'metadata'

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}",
  "format": "full"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "threadId": "thread_xyz789",
    "labelIds": ["INBOX", "UNREAD"],
    "snippet": "Hi, I wanted to follow up on...",
    "headers": {
      "from": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Meeting Follow-up",
      "date": "Mon, 15 Jan 2024 10:30:00 +0000"
    },
    "body": {
      "plain": "Hi, I wanted to follow up on our discussion.",
      "html": "<p>Hi, I wanted to follow up on our discussion.</p>"
    },
    "attachments": []
  }
}

sendMessage

Send an email message with optional CC, BCC, and attachments.

Parameters:

Parameter	Type	Required	Description
to	TEXT	Yes	Recipient email address
subject	TEXT	Yes	Email subject line
body	TEXT	Yes	Email body content (plain text)
cc	TEXT	No	CC recipients (comma-separated)
bcc	TEXT	No	BCC recipients (comma-separated)
threadId	TEXT	No	Thread ID for replies
attachments	TEXT	No	JSON array: [`{filename, mimeType, content}`]

Configuration Example:

{
  "to": "{{ctx.vars.customerEmail}}",
  "subject": "Order Confirmation #{{ctx.vars.orderId}}",
  "body": "Thank you for your order!\n\nYour order #{{ctx.vars.orderId}} has been confirmed.\n\nTotal: ${{ctx.vars.orderTotal}}",
  "cc": "{{ctx.vars.salesEmail}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_new123",
    "threadId": "thread_new456",
    "labelIds": ["SENT"]
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "The recipient email address is invalid"
  }
}

trashMessage

Move a message to the trash folder.

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message to trash

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "labelIds": ["TRASH"]
  }
}

untrashMessage

Restore a message from trash to its original location.

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message to restore

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "labelIds": ["INBOX"]
  }
}

deleteMessage

Permanently delete a message (bypasses trash).

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message to delete

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "deleted": true
  }
}

modifyMessage

Add or remove labels from a message.

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message to modify
addLabelIds	TEXT	No	Comma-separated label IDs to add
removeLabelIds	TEXT	No	Comma-separated label IDs to remove

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}",
  "addLabelIds": "STARRED,{{ctx.vars.customLabelId}}",
  "removeLabelIds": "UNREAD"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "labelIds": ["INBOX", "STARRED", "Label_123"]
  }
}

batchModifyMessages

Modify labels on multiple messages at once.

Parameters:

Parameter	Type	Required	Description
messageIds	TEXT	Yes	Comma-separated message IDs
addLabelIds	TEXT	No	Comma-separated label IDs to add
removeLabelIds	TEXT	No	Comma-separated label IDs to remove

Configuration Example:

{
  "messageIds": "{{ctx.vars.messageIds}}",
  "removeLabelIds": "UNREAD"
}

Success Response:

{
  "success": true,
  "data": {
    "modifiedCount": 5
  }
}

batchDeleteMessages

Permanently delete multiple messages at once.

Parameters:

Parameter	Type	Required	Description
messageIds	TEXT	Yes	Comma-separated message IDs to delete

Configuration Example:

{
  "messageIds": "{{ctx.vars.messageIds}}"
}

Success Response:

{
  "success": true,
  "data": {
    "deletedCount": 3
  }
}

getAttachment

Download an attachment from a message.

Parameters:

Parameter	Type	Required	Description
messageId	TEXT	Yes	The ID of the message containing the attachment
attachmentId	TEXT	Yes	The ID of the attachment to download

Configuration Example:

{
  "messageId": "{{ctx.vars.messageId}}",
  "attachmentId": "{{ctx.vars.attachmentId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "attachmentId": "att_xyz789",
    "size": 102400,
    "data": "base64_encoded_content"
  }
}

Labels

listLabels

List all labels in the user's mailbox.

Parameters:

No additional parameters required.

Configuration Example:

{}

Success Response:

{
  "success": true,
  "data": {
    "labels": [
      {"id": "INBOX", "name": "INBOX", "type": "system"},
      {"id": "SENT", "name": "SENT", "type": "system"},
      {"id": "Label_1", "name": "Work", "type": "user"},
      {"id": "Label_2", "name": "Personal", "type": "user"}
    ]
  }
}

getLabel

Get detailed information about a specific label.

Parameters:

Parameter	Type	Required	Description
labelId	TEXT	Yes	The ID of the label to retrieve

Configuration Example:

{
  "labelId": "{{ctx.vars.labelId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "Label_1",
    "name": "Work",
    "type": "user",
    "messagesTotal": 245,
    "messagesUnread": 12,
    "threadsTotal": 180,
    "threadsUnread": 8,
    "color": {
      "backgroundColor": "#4285f4",
      "textColor": "#ffffff"
    }
  }
}

createLabel

Create a new label in the user's mailbox.

Parameters:

Parameter	Type	Required	Description
name	TEXT	Yes	Display name for the label
labelListVisibility	TEXT	No	'labelShow', 'labelShowIfUnread', 'labelHide'
messageListVisibility	TEXT	No	'show' or 'hide'
backgroundColor	TEXT	No	Background color hex code
textColor	TEXT	No	Text color hex code

Configuration Example:

{
  "name": "{{ctx.vars.labelName}}",
  "labelListVisibility": "labelShow",
  "backgroundColor": "#16a765",
  "textColor": "#ffffff"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "Label_new123",
    "name": "Projects",
    "type": "user"
  }
}

updateLabel

Update an existing label's properties.

Parameters:

Parameter	Type	Required	Description
labelId	TEXT	Yes	The ID of the label to update
name	TEXT	No	New display name
labelListVisibility	TEXT	No	'labelShow', 'labelShowIfUnread', 'labelHide'
messageListVisibility	TEXT	No	'show' or 'hide'
backgroundColor	TEXT	No	Background color hex code
textColor	TEXT	No	Text color hex code

Configuration Example:

{
  "labelId": "{{ctx.vars.labelId}}",
  "name": "{{ctx.vars.newLabelName}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "Label_1",
    "name": "Work Projects"
  }
}

deleteLabel

Permanently delete a label.

Parameters:

Parameter	Type	Required	Description
labelId	TEXT	Yes	The ID of the label to delete

Configuration Example:

{
  "labelId": "{{ctx.vars.labelId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Threads

listThreads

List conversation threads in the user's mailbox.

Parameters:

Parameter	Type	Required	Description
maxResults	INT	No	Maximum number of threads (1-500, default 100)
q	TEXT	No	Gmail search query
labelIds	TEXT	No	Comma-separated label IDs to filter by
pageToken	TEXT	No	Page token for pagination
includeSpamTrash	BOOLEAN	No	Include SPAM and TRASH threads

Configuration Example:

{
  "maxResults": 20,
  "q": "subject:{{ctx.vars.searchSubject}}",
  "labelIds": "INBOX"
}

Success Response:

{
  "success": true,
  "data": {
    "threads": [
      {"id": "thread_abc123", "snippet": "Let's schedule a meeting...", "historyId": "12345"},
      {"id": "thread_def456", "snippet": "Meeting notes from today...", "historyId": "12346"}
    ],
    "nextPageToken": "token123",
    "resultSizeEstimate": 15
  }
}

getThread

Get a specific thread with all its messages.

Parameters:

Parameter	Type	Required	Description
threadId	TEXT	Yes	The ID of the thread to retrieve
format	TEXT	No	Format: 'full', 'metadata', 'minimal', 'raw'
metadataHeaders	TEXT	No	Headers to include when format is 'metadata'

Configuration Example:

{
  "threadId": "{{ctx.vars.threadId}}",
  "format": "full"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "thread_abc123",
    "historyId": "12345",
    "messages": [
      {
        "id": "msg_001",
        "snippet": "Hi, when can we meet?",
        "headers": {
          "from": "colleague@example.com",
          "subject": "Meeting Request"
        }
      },
      {
        "id": "msg_002",
        "snippet": "How about Tuesday at 2pm?",
        "headers": {
          "from": "user@gmail.com",
          "subject": "Re: Meeting Request"
        }
      }
    ]
  }
}

trashThread

Move a thread to trash.

Parameters:

Parameter	Type	Required	Description
threadId	TEXT	Yes	The ID of the thread to trash

Configuration Example:

{
  "threadId": "{{ctx.vars.threadId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "thread_abc123"
  }
}

untrashThread

Restore a thread from trash.

Parameters:

Parameter	Type	Required	Description
threadId	TEXT	Yes	The ID of the thread to restore

Configuration Example:

{
  "threadId": "{{ctx.vars.threadId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "thread_abc123"
  }
}

deleteThread

Permanently delete a thread.

Parameters:

Parameter	Type	Required	Description
threadId	TEXT	Yes	The ID of the thread to delete

Configuration Example:

{
  "threadId": "{{ctx.vars.threadId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "deleted": true
  }
}

modifyThread

Add or remove labels from a thread.

Parameters:

Parameter	Type	Required	Description
threadId	TEXT	Yes	The ID of the thread to modify
addLabelIds	TEXT	No	Comma-separated label IDs to add
removeLabelIds	TEXT	No	Comma-separated label IDs to remove

Configuration Example:

{
  "threadId": "{{ctx.vars.threadId}}",
  "addLabelIds": "STARRED",
  "removeLabelIds": "UNREAD"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "thread_abc123"
  }
}

Drafts

listDrafts

List drafts in the user's mailbox.

Parameters:

Parameter	Type	Required	Description
maxResults	INT	No	Maximum number of drafts (1-500, default 100)
q	TEXT	No	Gmail search query
pageToken	TEXT	No	Page token for pagination
includeSpamTrash	BOOLEAN	No	Include SPAM and TRASH drafts

Configuration Example:

{
  "maxResults": 10
}

Success Response:

{
  "success": true,
  "data": {
    "drafts": [
      {"id": "draft_abc123", "message": {"id": "msg_draft001"}},
      {"id": "draft_def456", "message": {"id": "msg_draft002"}}
    ],
    "nextPageToken": "token123"
  }
}

getDraft

Get a specific draft by ID.

Parameters:

Parameter	Type	Required	Description
draftId	TEXT	Yes	The ID of the draft to retrieve
format	TEXT	No	Format: 'full', 'metadata', 'minimal', 'raw'

Configuration Example:

{
  "draftId": "{{ctx.vars.draftId}}",
  "format": "full"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "draft_abc123",
    "message": {
      "id": "msg_draft001",
      "labelIds": ["DRAFT"],
      "snippet": "Draft content preview...",
      "headers": {
        "to": "recipient@example.com",
        "subject": "Draft: Project Proposal"
      }
    }
  }
}

createDraft

Create a new draft email.

Parameters:

Parameter	Type	Required	Description
to	TEXT	Yes	Recipient email address
subject	TEXT	Yes	Email subject line
body	TEXT	Yes	Email body content
cc	TEXT	No	CC recipients (comma-separated)
bcc	TEXT	No	BCC recipients (comma-separated)
threadId	TEXT	No	Thread ID to associate with

Configuration Example:

{
  "to": "{{ctx.vars.recipientEmail}}",
  "subject": "{{ctx.vars.emailSubject}}",
  "body": "{{ctx.vars.emailBody}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "draft_new123",
    "message": {
      "id": "msg_draft003",
      "labelIds": ["DRAFT"]
    }
  }
}

updateDraft

Update an existing draft.

Parameters:

Parameter	Type	Required	Description
draftId	TEXT	Yes	The ID of the draft to update
to	TEXT	Yes	Recipient email address
subject	TEXT	Yes	Email subject line
body	TEXT	Yes	Email body content
cc	TEXT	No	CC recipients (comma-separated)
bcc	TEXT	No	BCC recipients (comma-separated)
threadId	TEXT	No	Thread ID to associate with

Configuration Example:

{
  "draftId": "{{ctx.vars.draftId}}",
  "to": "{{ctx.vars.recipientEmail}}",
  "subject": "Updated: {{ctx.vars.emailSubject}}",
  "body": "{{ctx.vars.updatedBody}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "draft_abc123",
    "message": {
      "id": "msg_draft001_v2",
      "labelIds": ["DRAFT"]
    }
  }
}

deleteDraft

Permanently delete a draft.

Parameters:

Parameter	Type	Required	Description
draftId	TEXT	Yes	The ID of the draft to delete

Configuration Example:

{
  "draftId": "{{ctx.vars.draftId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "deleted": true
  }
}

sendDraft

Send an existing draft as an email.

Parameters:

Parameter	Type	Required	Description
draftId	TEXT	Yes	The ID of the draft to send

Configuration Example:

{
  "draftId": "{{ctx.vars.draftId}}"
}

Success Response:

{
  "success": true,
  "data": {
    "id": "msg_sent123",
    "threadId": "thread_xyz789",
    "labelIds": ["SENT"]
  }
}

Triggers

New Email

Triggered when new emails arrive or changes occur in Gmail via Google Cloud Pub/Sub integration.

Supported Events

Event Code	Event Name	Description
`messageAdded`	Messages Added	Triggered when a new message is received in the mailbox
`messageDeleted`	Messages Deleted	Triggered when a message is permanently deleted
`labelAdded`	Labels Added	Triggered when a label is applied to a message
`labelRemoved`	Labels Removed	Triggered when a label is removed from a message

Configuration Options

Option	Type	Required	Default	Description
`topicName`	TEXT	Yes	-	Google Cloud Pub/Sub topic name (projects/`{project}`/topics/`{topic}`)
`labelIds`	TEXT	No	INBOX	Comma-separated label IDs to watch (e.g., INBOX, UNREAD)
`labelFilterBehavior`	SELECT	No	include	Whether to include or exclude the specified labels
`historyTypes`	SELECT	No	messageAdded	Types of changes to track (see Supported Events)

Event Payload Examples

Messages Added (messageAdded):

{
  "eventType": "messageAdded",
  "emailAddress": "user@gmail.com",
  "historyId": "12345678",
  "changes": [{
    "message": {
      "id": "msg_abc123",
      "threadId": "thread_xyz789",
      "from": "sender@example.com",
      "to": "user@gmail.com",
      "subject": "New Message Subject",
      "snippet": "Message preview text...",
      "labelIds": ["INBOX", "UNREAD"],
      "internalDate": "1705312200000"
    }
  }]
}

Labels Added (labelAdded):

{
  "eventType": "labelAdded",
  "emailAddress": "user@gmail.com",
  "historyId": "12345679",
  "changes": [{
    "message": {
      "id": "msg_abc123",
      "threadId": "thread_xyz789"
    },
    "labelIds": ["STARRED"]
  }]
}

Messages Deleted (messageDeleted):

{
  "eventType": "messageDeleted",
  "emailAddress": "user@gmail.com",
  "historyId": "12345680",
  "changes": [{
    "message": {
      "id": "msg_abc123",
      "threadId": "thread_xyz789"
    }
  }]
}

Webhook Setup: See the Setup Guide for Pub/Sub prerequisites and webhook service configuration.

Use Cases

Order Confirmation Emails

Automatically send order confirmation emails when a new order is created in your e-commerce system.

Trigger: Webhook from your e-commerce platform on new order
Action: Gmail sendMessage with order details
Result: Customer receives personalized confirmation email

{
  "to": "{{ctx.steps.order.customerEmail}}",
  "subject": "Order Confirmed #{{ctx.steps.order.orderId}}",
  "body": "Thank you for your order!\n\nOrder: #{{ctx.steps.order.orderId}}\nTotal: ${{ctx.steps.order.total}}\n\nWe'll notify you when it ships."
}

Support Ticket Creation

Monitor inbox for support requests and automatically create tickets in your helpdesk system.

Trigger: Gmail New Email trigger (label: Support)
Action: Parse email content using getMessage
Action: Create ticket in Linear with email details
Action: Send acknowledgment reply via sendMessage

Email Classification & Routing

Automatically classify incoming emails and route them to appropriate labels.

Trigger: Gmail New Email trigger
Action: Analyze email content with AI
Action: Apply appropriate labels via modifyMessage
Action: Forward to relevant team member if urgent

Daily Email Digest

Compile and send a daily summary of important emails.

Trigger: Scheduled trigger (daily at 9 AM)
Action: Gmail listMessages with query for important/unread
Action: Compile summary of messages
Action: Gmail sendMessage with digest to manager

Attachment Processing

Automatically process attachments from incoming emails.

Trigger: Gmail New Email trigger
Action: Check for attachments in message
Action: Download attachment via getAttachment
Action: Process/store attachment (e.g., via HTTP Request node)
Action: Send confirmation reply

Gmail

Setup Guide

Changelog

On this page