List

List Gmail messages

Retrieve a list of messages from Gmail inbox or specific labels using Gmail API

yaml
type: "io.kestra.plugin.googleworkspace.mail.List"

Examples

List all messages in inbox

yaml
id: list_messages
namespace: company.team

tasks:
  - id: list_messages
    type: io.kestra.plugin.googleworkspace.mail.List
    clientId: "{{ secret('GMAIL_CLIENT_ID') }}"
    clientSecret: "{{ secret('GMAIL_CLIENT_SECRET') }}"
    refreshToken: "{{ secret('GMAIL_REFRESH_TOKEN') }}"
    maxResults: 10

List unread messages

yaml
id: list_unread_messages
namespace: company.team

tasks:
  - id: list_unread
    type: io.kestra.plugin.googleworkspace.mail.List
    clientId: "{{ secret('GMAIL_CLIENT_ID') }}"
    clientSecret: "{{ secret('GMAIL_CLIENT_SECRET') }}"
    refreshToken: "{{ secret('GMAIL_REFRESH_TOKEN') }}"
    query: is:unread
    labelIds:
      - INBOX
    maxResults: 50
    fetchType: STORE

Get first message only

yaml
id: get_first_message
namespace: company.team

tasks:
  - id: get_first
    type: io.kestra.plugin.googleworkspace.mail.List
    clientId: "{{ secret('GMAIL_CLIENT_ID') }}"
    clientSecret: "{{ secret('GMAIL_CLIENT_SECRET') }}"
    refreshToken: "{{ secret('GMAIL_REFRESH_TOKEN') }}"
    fetchType: FETCH_ONE
    maxResults: 1

Properties

clientId *string

OAuth 2.0 Client ID

The OAuth 2.0 client ID from Google Cloud Console

clientSecret *string

OAuth 2.0 Client Secret

The OAuth 2.0 client secret from Google Cloud Console

refreshToken *string

OAuth 2.0 Refresh Token

The OAuth 2.0 refresh token obtained through the authorization flow

accessToken string

OAuth 2.0 Access Token

The OAuth 2.0 access token (optional, will be generated from refresh token if not provided)

fetchType string

Default FETCH

Possible Values

STOREFETCHFETCH_ONENONE

The way you want to store the data

FETCH - outputs the messages as an output FETCH_ONE - outputs the first message only as an output STORE - stores all messages to a file NONE - no output

includeSpamTrash booleanstring

Default false

Include spam and trash

Whether to include messages from SPAM and TRASH in the results

labelIds array

SubType string

Label IDs to filter messages

List of label IDs to restrict the search (e.g., INBOX, SENT, DRAFT, UNREAD)

maxResults integerstring

Default 100

Maximum number of results

Maximum number of messages to return (default: 100, max: 500)

query string

Gmail search query

Search query using Gmail search syntax (e.g., 'is: unread', 'from: [email protected]', 'subject: important')

readTimeout integerstring

Default 120

The read timeout for the request (in seconds)

scopes array

SubType string

Default

["https://www.googleapis.com/auth/gmail.modify","https://www.googleapis.com/auth/gmail.readonly","https://www.googleapis.com/auth/gmail.send"]

The OAuth scopes to use

List of OAuth 2.0 scopes required for the operation

Outputs

message Message

Single message (when fetchType is FETCH_ONE)

messages array

SubType

List of messages (when fetchType is FETCH)

nextPageToken string

Token for retrieving next page of results

resultSizeEstimate integer

Total estimated number of results

uri string

Format uri

URI of the stored messages file (when fetchType is STORE)

Definitions

Gmail message representation

attachments array

SubType

List of attachments in the message

bcc array

SubType string

The BCC recipient email addresses

cc array

SubType string

The CC recipient email addresses

from string

The sender email address

headers object

SubType string

The parsed headers of the message

historyId string

The ID of the last history record that modified this message

id string

The immutable ID of the message

internalDate string

Format date-time

The internal message creation timestamp

labelIds array

SubType string

List of IDs of labels applied to this message

raw string

The entire email message in an RFC 2822 formatted and base64url encoded string

sizeEstimate integer

Estimated size in bytes of the message

snippet string

A short part of the message text

subject string

The message subject

textHtml string

The HTML body of the message

textPlain string

The plain text body of the message

threadId string

The ID of the thread the message belongs to

to array

SubType string

The recipient email addresses

Gmail message attachment

attachmentId string

The attachment ID

data string

The attachment data as a base64url encoded string

filename string

The filename of the attachment

mimeType string

The MIME type of the attachment file

size integer

The size of the attachment in bytes

​List

List