Gmail full reference

This connector is optimized for AI agents. For the data replication connector, see Gmail.

This is the full reference documentation for the Gmail agent connector.

Supported entities and actions

The Gmail connector supports the following entities and actions.

Entity	Actions
Profile	Get, Context Store Search, Context Store SQL Query
Messages	List, Get, Create, Update, Context Store Search, Context Store SQL Query
Labels	List, Create, Get, Update, Delete, Context Store Search, Context Store SQL Query
Drafts	List, Create, Get, Update, Delete, Context Store Search, Context Store SQL Query
Drafts Send	Create
Threads	List, Get, Context Store Search, Context Store SQL Query
Messages Trash	Create
Messages Untrash	Create

Profile

Profile Get

Gets the current user's Gmail profile including email address and mailbox statistics

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "profile",
  "action": "get"
}'

Python SDK

await gmail.profile.get()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profile",
    "action": "get"
}'

Response Schema

Records

Field Name	Type	Description
`emailAddress`	`string \| null`
`messagesTotal`	`integer \| null`
`threadsTotal`	`integer \| null`
`historyId`	`string \| null`

Profile Context Store Search

Search and filter profile records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "profile",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "emailAddress": "<str>"
        }
      }
    }
  }
}'

Python SDK

await gmail.profile.context_store_search(
    query={"filter": {"eq": {"emailAddress": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profile",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"emailAddress": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's `meta.cursor`
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`emailAddress`	`string`	Email address of the authenticated Gmail account
`historyId`	`string`	Mailbox history record identifier used for incremental sync
`messagesTotal`	`number`	Total number of messages currently in the mailbox
`threadsTotal`	`number`	Total number of threads currently in the mailbox

Response Schema

Field Name	Type	Description
`data`	`array`	List of matching records
`meta`	`object`	Pagination metadata
`meta.has_more`	`boolean`	Whether additional pages are available
`meta.cursor`	`string \| null`	Cursor for next page of results
`meta.took_ms`	`number \| null`	Query execution time in milliseconds
`data[].emailAddress`	`string`	Email address of the authenticated Gmail account
`data[].historyId`	`string`	Mailbox history record identifier used for incremental sync
`data[].messagesTotal`	`number`	Total number of messages currently in the mailbox
`data[].threadsTotal`	`number`	Total number of threads currently in the mailbox

Profile Context Store SQL Query

Run a SQL query against profile records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "profile",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await gmail.profile.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profile",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`sql`	`string`	Yes	SQL query to execute against this entity's Context Store data
`limit`	`integer`	No	Maximum results to return

Response Schema

Field Name	Type	Description
`data`	`array`	Projected rows, with dictionary keys matching the selected columns
`meta`	`object`	Query metadata
`meta.has_more`	`boolean`	Whether the result was limited and more rows are available
`meta.cursor`	`null`	SQL query results do not use cursor pagination
`meta.took_ms`	`number \| null`	Query execution time in milliseconds

Messages

Messages List

Lists the messages in the user's mailbox. Returns message IDs and thread IDs.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "list"
}'

Python SDK

await gmail.messages.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
`maxResults`	`integer`	No	Maximum number of messages to return (1-500)
`pageToken`	`string`	No	Page token to retrieve a specific page of results
`q`	`string`	No	Gmail search query (same format as Gmail search box, e.g. "from:user@example.com", "is:unread", "subject:hello")
`labelIds`	`string`	No	Only return messages with labels matching all of the specified label IDs (comma-separated)
`includeSpamTrash`	`boolean`	No	Include messages from SPAM and TRASH in the results

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`

Field Name	Type	Description
`nextPageToken`	`string \| null`
`resultSizeEstimate`	`integer \| null`

Messages Get

Gets the full email message content including headers, body, and attachments metadata

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "get",
  "params": {
    "messageId": "<str>"
  }
}'

Python SDK

await gmail.messages.get(
    message_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "get",
    "params": {
        "messageId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message to retrieve
`format`	`"full" \| "metadata" \| "minimal" \| "raw"`	No	The format to return the message in (full, metadata, minimal, raw)
`metadataHeaders`	`string`	No	When format is METADATA, only include headers specified (comma-separated)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Messages Create

Sends a new email message. The message should be provided as a base64url-encoded RFC 2822 formatted string in the 'raw' field. Build the complete MIME message first, including headers such as To and Subject plus a blank line before the body, then base64url-encode that message before calling this operation.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "create",
  "params": {
    "raw": "<str>",
    "threadId": "<str>"
  }
}'

Python SDK

await gmail.messages.create(
    raw="<str>",
    thread_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "create",
    "params": {
        "raw": "<str>",
        "threadId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`raw`	`string`	Yes	Base64url-encoded RFC 2822/MIME email; construct headers plus a blank line plus body, then URL-safe-base64 encode the UTF-8 bytes before sending.
`threadId`	`string`	No	The thread ID to reply to (for threading replies in a conversation)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Messages Update

Modifies the labels on a message. Use this to archive (remove INBOX label), mark as read (remove UNREAD label), mark as unread (add UNREAD label), star (add STARRED label), or apply custom labels.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "update",
  "params": {
    "addLabelIds": [],
    "removeLabelIds": [],
    "messageId": "<str>"
  }
}'

Python SDK

await gmail.messages.update(
    add_label_ids=[],
    remove_label_ids=[],
    message_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "update",
    "params": {
        "addLabelIds": [],
        "removeLabelIds": [],
        "messageId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`addLabelIds`	`array<string>`	No	A list of label IDs to add to the message (e.g. STARRED, UNREAD, or custom label IDs)
`removeLabelIds`	`array<string>`	No	A list of label IDs to remove from the message (e.g. INBOX to archive, UNREAD to mark as read)
`messageId`	`string`	Yes	The ID of the message to modify

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Messages Context Store Search

Search and filter messages records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

await gmail.messages.context_store_search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's `meta.cursor`
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Unique identifier for the message
`threadId`	`string`	Identifier of the thread this message belongs to
`labelIds`	`array`	Labels applied to the message
`snippet`	`string`	Short snippet of the message text
`historyId`	`string`	Mailbox history record identifier for the message
`internalDate`	`string`	Internal message creation timestamp in epoch milliseconds
`sizeEstimate`	`integer`	Estimated size of the message in bytes
`payload`	`object`	Parsed MIME payload including headers, body, nested MIME parts, and attachment metadata. Use payload.headers for sender, recipients, subject, date, and other email headers.

Response Schema

Field Name	Type	Description
`data`	`array`	List of matching records
`meta`	`object`	Pagination metadata
`meta.has_more`	`boolean`	Whether additional pages are available
`meta.cursor`	`string \| null`	Cursor for next page of results
`meta.took_ms`	`number \| null`	Query execution time in milliseconds
`data[].id`	`string`	Unique identifier for the message
`data[].threadId`	`string`	Identifier of the thread this message belongs to
`data[].labelIds`	`array`	Labels applied to the message
`data[].snippet`	`string`	Short snippet of the message text
`data[].historyId`	`string`	Mailbox history record identifier for the message
`data[].internalDate`	`string`	Internal message creation timestamp in epoch milliseconds
`data[].sizeEstimate`	`integer`	Estimated size of the message in bytes
`data[].payload`	`object`	Parsed MIME payload including headers, body, nested MIME parts, and attachment metadata. Use payload.headers for sender, recipients, subject, date, and other email headers.

Messages Context Store SQL Query

Run a SQL query against messages records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await gmail.messages.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`sql`	`string`	Yes	SQL query to execute against this entity's Context Store data
`limit`	`integer`	No	Maximum results to return

Response Schema

Field Name	Type	Description
`data`	`array`	Projected rows, with dictionary keys matching the selected columns
`meta`	`object`	Query metadata
`meta.has_more`	`boolean`	Whether the result was limited and more rows are available
`meta.cursor`	`null`	SQL query results do not use cursor pagination
`meta.took_ms`	`number \| null`	Query execution time in milliseconds

Labels

Labels List

Lists all labels in the user's mailbox including system and user-created labels

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "list"
}'

Python SDK

await gmail.labels.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "list"
}'

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`type`	`string \| null`
`messageListVisibility`	`string \| null`
`labelListVisibility`	`string \| null`
`messagesTotal`	`integer \| null`
`messagesUnread`	`integer \| null`
`threadsTotal`	`integer \| null`
`threadsUnread`	`integer \| null`
`color`	`object \| any`

Labels Create

Creates a new label in the user's mailbox

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "create",
  "params": {
    "name": "<str>",
    "messageListVisibility": "<str>",
    "labelListVisibility": "<str>",
    "color": {}
  }
}'

Python SDK

await gmail.labels.create(
    name="<str>",
    message_list_visibility="<str>",
    label_list_visibility="<str>",
    color={}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "create",
    "params": {
        "name": "<str>",
        "messageListVisibility": "<str>",
        "labelListVisibility": "<str>",
        "color": {}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`name`	`string`	Yes	The display name of the label
`messageListVisibility`	`"show" \| "hide"`	No	The visibility of messages with this label in the message list (show or hide)
`labelListVisibility`	`"labelShow" \| "labelShowIfUnread" \| "labelHide"`	No	The visibility of the label in the label list
`color`	`object`	No	The color to assign to the label
`color.textColor`	`string`	No	The text color of the label as a hex string (#RRGGBB)
`color.backgroundColor`	`string`	No	The background color of the label as a hex string (#RRGGBB)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`type`	`string \| null`
`messageListVisibility`	`string \| null`
`labelListVisibility`	`string \| null`
`messagesTotal`	`integer \| null`
`messagesUnread`	`integer \| null`
`threadsTotal`	`integer \| null`
`threadsUnread`	`integer \| null`
`color`	`object \| any`

Labels Get

Gets a specific label by ID including message and thread counts

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "get",
  "params": {
    "labelId": "<str>"
  }
}'

Python SDK

await gmail.labels.get(
    label_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "get",
    "params": {
        "labelId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`labelId`	`string`	Yes	The ID of the label to retrieve

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`type`	`string \| null`
`messageListVisibility`	`string \| null`
`labelListVisibility`	`string \| null`
`messagesTotal`	`integer \| null`
`messagesUnread`	`integer \| null`
`threadsTotal`	`integer \| null`
`threadsUnread`	`integer \| null`
`color`	`object \| any`

Labels Update

Updates the specified label

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "update",
  "params": {
    "id": "<str>",
    "name": "<str>",
    "messageListVisibility": "<str>",
    "labelListVisibility": "<str>",
    "color": {},
    "labelId": "<str>"
  }
}'

Python SDK

await gmail.labels.update(
    id="<str>",
    name="<str>",
    message_list_visibility="<str>",
    label_list_visibility="<str>",
    color={},
    label_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "update",
    "params": {
        "id": "<str>",
        "name": "<str>",
        "messageListVisibility": "<str>",
        "labelListVisibility": "<str>",
        "color": {},
        "labelId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`id`	`string`	No	The ID of the label (must match the path parameter)
`name`	`string`	No	The new display name of the label
`messageListVisibility`	`"show" \| "hide"`	No	The visibility of messages with this label in the message list
`labelListVisibility`	`"labelShow" \| "labelShowIfUnread" \| "labelHide"`	No	The visibility of the label in the label list
`color`	`object`	No	The color to assign to the label
`color.textColor`	`string`	No	The text color of the label as a hex string (#RRGGBB)
`color.backgroundColor`	`string`	No	The background color of the label as a hex string (#RRGGBB)
`labelId`	`string`	Yes	The ID of the label to update

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`type`	`string \| null`
`messageListVisibility`	`string \| null`
`labelListVisibility`	`string \| null`
`messagesTotal`	`integer \| null`
`messagesUnread`	`integer \| null`
`threadsTotal`	`integer \| null`
`threadsUnread`	`integer \| null`
`color`	`object \| any`

Labels Delete

Deletes the specified label and removes it from any messages and threads

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "delete",
  "params": {
    "labelId": "<str>"
  }
}'

Python SDK

await gmail.labels.delete(
    label_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "delete",
    "params": {
        "labelId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`labelId`	`string`	Yes	The ID of the label to delete

Labels Context Store Search

Search and filter labels records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

await gmail.labels.context_store_search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's `meta.cursor`
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Unique identifier for the label
`name`	`string`	Display name of the label
`type`	`string`	Label type: `system` or `user`
`labelListVisibility`	`string`	Visibility of the label in the label list
`messageListVisibility`	`string`	Visibility of the label when viewing a message list

Response Schema

Field Name	Type	Description
`data`	`array`	List of matching records
`meta`	`object`	Pagination metadata
`meta.has_more`	`boolean`	Whether additional pages are available
`meta.cursor`	`string \| null`	Cursor for next page of results
`meta.took_ms`	`number \| null`	Query execution time in milliseconds
`data[].id`	`string`	Unique identifier for the label
`data[].name`	`string`	Display name of the label
`data[].type`	`string`	Label type: `system` or `user`
`data[].labelListVisibility`	`string`	Visibility of the label in the label list
`data[].messageListVisibility`	`string`	Visibility of the label when viewing a message list

Labels Context Store SQL Query

Run a SQL query against labels records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "labels",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await gmail.labels.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "labels",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`sql`	`string`	Yes	SQL query to execute against this entity's Context Store data
`limit`	`integer`	No	Maximum results to return

Response Schema

Field Name	Type	Description
`data`	`array`	Projected rows, with dictionary keys matching the selected columns
`meta`	`object`	Query metadata
`meta.has_more`	`boolean`	Whether the result was limited and more rows are available
`meta.cursor`	`null`	SQL query results do not use cursor pagination
`meta.took_ms`	`number \| null`	Query execution time in milliseconds

Drafts

Drafts List

Lists the drafts in the user's mailbox

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "list"
}'

Python SDK

await gmail.drafts.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
`maxResults`	`integer`	No	Maximum number of drafts to return (1-500)
`pageToken`	`string`	No	Page token to retrieve a specific page of results
`q`	`string`	No	Gmail search query to filter drafts
`includeSpamTrash`	`boolean`	No	Include drafts from SPAM and TRASH in the results

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`message`	`object \| any`

Field Name	Type	Description
`nextPageToken`	`string \| null`
`resultSizeEstimate`	`integer \| null`

Drafts Create

Creates a new draft with the specified message content

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "create",
  "params": {
    "message": {
      "raw": "<str>"
    }
  }
}'

Python SDK

await gmail.drafts.create(
    message={
        "raw": "<str>"
    }
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "create",
    "params": {
        "message": {
            "raw": "<str>"
        }
    }
}'

Parameters

Parameter Name	Type	Required	Description
`message`	`object`	Yes	The draft message content encoded in Gmail raw message format
`message.raw`	`string`	Yes	Base64url-encoded RFC 2822/MIME email; construct headers plus a blank line plus body, then URL-safe-base64 encode the UTF-8 bytes before creating or updating the draft.
`message.threadId`	`string`	No	The thread ID for the draft (for threading in a conversation)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`message`	`object \| any`

Drafts Get

Gets the specified draft including its message content

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "get",
  "params": {
    "draftId": "<str>"
  }
}'

Python SDK

await gmail.drafts.get(
    draft_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "get",
    "params": {
        "draftId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`draftId`	`string`	Yes	The ID of the draft to retrieve
`format`	`"full" \| "metadata" \| "minimal" \| "raw"`	No	The format to return the draft message in (full, metadata, minimal, raw)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`message`	`object \| any`

Drafts Update

Replaces a draft's content with the specified message content

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "update",
  "params": {
    "message": {
      "raw": "<str>"
    },
    "draftId": "<str>"
  }
}'

Python SDK

await gmail.drafts.update(
    message={
        "raw": "<str>"
    },
    draft_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "update",
    "params": {
        "message": {
            "raw": "<str>"
        },
        "draftId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`message`	`object`	Yes	The draft message content encoded in Gmail raw message format
`message.raw`	`string`	Yes	Base64url-encoded RFC 2822/MIME email; construct headers plus a blank line plus body, then URL-safe-base64 encode the UTF-8 bytes before creating or updating the draft.
`message.threadId`	`string`	No	The thread ID for the draft (for threading in a conversation)
`draftId`	`string`	Yes	The ID of the draft to update

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`message`	`object \| any`

Drafts Delete

Immediately and permanently deletes the specified draft (does not move to trash)

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "delete",
  "params": {
    "draftId": "<str>"
  }
}'

Python SDK

await gmail.drafts.delete(
    draft_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "delete",
    "params": {
        "draftId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`draftId`	`string`	Yes	The ID of the draft to delete

Drafts Context Store Search

Search and filter drafts records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

await gmail.drafts.context_store_search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's `meta.cursor`
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Unique identifier for the draft
`message`	`object`	Draft message payload (headers, body, and metadata)

Response Schema

Field Name	Type	Description
`data`	`array`	List of matching records
`meta`	`object`	Pagination metadata
`meta.has_more`	`boolean`	Whether additional pages are available
`meta.cursor`	`string \| null`	Cursor for next page of results
`meta.took_ms`	`number \| null`	Query execution time in milliseconds
`data[].id`	`string`	Unique identifier for the draft
`data[].message`	`object`	Draft message payload (headers, body, and metadata)

Drafts Context Store SQL Query

Run a SQL query against drafts records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await gmail.drafts.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`sql`	`string`	Yes	SQL query to execute against this entity's Context Store data
`limit`	`integer`	No	Maximum results to return

Response Schema

Field Name	Type	Description
`data`	`array`	Projected rows, with dictionary keys matching the selected columns
`meta`	`object`	Query metadata
`meta.has_more`	`boolean`	Whether the result was limited and more rows are available
`meta.cursor`	`null`	SQL query results do not use cursor pagination
`meta.took_ms`	`number \| null`	Query execution time in milliseconds

Drafts Send

Drafts Send Create

Sends the specified existing draft to its recipients

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "drafts_send",
  "action": "create",
  "params": {
    "id": "<str>"
  }
}'

Python SDK

await gmail.drafts_send.create(
    id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "drafts_send",
    "action": "create",
    "params": {
        "id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`id`	`string`	Yes	The ID of the draft to send

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Threads

Threads List

Lists the threads in the user's mailbox

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "threads",
  "action": "list"
}'

Python SDK

await gmail.threads.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "threads",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
`maxResults`	`integer`	No	Maximum number of threads to return (1-500)
`pageToken`	`string`	No	Page token to retrieve a specific page of results
`q`	`string`	No	Gmail search query to filter threads
`labelIds`	`string`	No	Only return threads with labels matching all of the specified label IDs (comma-separated)
`includeSpamTrash`	`boolean`	No	Include threads from SPAM and TRASH in the results

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`snippet`	`string \| null`
`historyId`	`string \| null`

Threads Get

Gets the specified thread including all messages in the conversation

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "threads",
  "action": "get",
  "params": {
    "threadId": "<str>"
  }
}'

Python SDK

await gmail.threads.get(
    thread_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "threads",
    "action": "get",
    "params": {
        "threadId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`threadId`	`string`	Yes	The ID of the thread to retrieve
`format`	`"full" \| "metadata" \| "minimal"`	No	The format to return the messages in (full, metadata, minimal)
`metadataHeaders`	`string`	No	When format is METADATA, only include headers specified (comma-separated)

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`snippet`	`string \| null`
`historyId`	`string \| null`
`messages`	`array \| null`
`messages[].id`	`string`
`messages[].threadId`	`string \| null`
`messages[].labelIds`	`array \| null`
`messages[].snippet`	`string \| null`
`messages[].historyId`	`string \| null`
`messages[].internalDate`	`string \| null`
`messages[].sizeEstimate`	`integer \| null`
`messages[].raw`	`string \| null`
`messages[].payload`	`object \| any`

Threads Context Store Search

Search and filter threads records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "threads",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

await gmail.threads.context_store_search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "threads",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's `meta.cursor`
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Unique identifier for the thread
`historyId`	`string`	Mailbox history record identifier for the thread
`snippet`	`string`	Short snippet of the thread's most recent message

Response Schema

Field Name	Type	Description
`data`	`array`	List of matching records
`meta`	`object`	Pagination metadata
`meta.has_more`	`boolean`	Whether additional pages are available
`meta.cursor`	`string \| null`	Cursor for next page of results
`meta.took_ms`	`number \| null`	Query execution time in milliseconds
`data[].id`	`string`	Unique identifier for the thread
`data[].historyId`	`string`	Mailbox history record identifier for the thread
`data[].snippet`	`string`	Short snippet of the thread's most recent message

Threads Context Store SQL Query

Run a SQL query against threads records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "threads",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await gmail.threads.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "threads",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`sql`	`string`	Yes	SQL query to execute against this entity's Context Store data
`limit`	`integer`	No	Maximum results to return

Response Schema

Field Name	Type	Description
`data`	`array`	Projected rows, with dictionary keys matching the selected columns
`meta`	`object`	Query metadata
`meta.has_more`	`boolean`	Whether the result was limited and more rows are available
`meta.cursor`	`null`	SQL query results do not use cursor pagination
`meta.took_ms`	`number \| null`	Query execution time in milliseconds

Messages Trash

Messages Trash Create

Moves the specified message to the trash

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages_trash",
  "action": "create",
  "params": {
    "messageId": "<str>"
  }
}'

Python SDK

await gmail.messages_trash.create(
    message_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages_trash",
    "action": "create",
    "params": {
        "messageId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message to trash

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Messages Untrash

Messages Untrash Create

Removes the specified message from the trash

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "gmail",
  "entity": "messages_untrash",
  "action": "create",
  "params": {
    "messageId": "<str>"
  }
}'

Python SDK

await gmail.messages_untrash.create(
    message_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "messages_untrash",
    "action": "create",
    "params": {
        "messageId": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message to untrash

Response Schema

Records

Field Name	Type	Description
`id`	`string`
`threadId`	`string \| null`
`labelIds`	`array \| null`
`snippet`	`string \| null`
`historyId`	`string \| null`
`internalDate`	`string \| null`
`sizeEstimate`	`integer \| null`
`raw`	`string \| null`
`payload`	`object \| any`

Supported entities and actions​

Profile​

Profile Get​

CLI​

Python SDK​

API​

Records​

Profile Context Store Search​

CLI​

Python SDK​

API​

Parameters​

Searchable Fields​

Profile Context Store SQL Query​

CLI​

Python SDK​

API​

Parameters​

Messages​

Messages List​

CLI​

Python SDK​

API​

Parameters​

Records​

Meta​

Messages Get​

CLI​

Python SDK​

API​

Parameters​

Records​

Messages Create​

CLI​

Python SDK​

API​

Parameters​

Records​

Messages Update​

CLI​

Python SDK​

API​

Parameters​

Records​

Messages Context Store Search​

CLI​

Python SDK​

API​

Parameters​

Searchable Fields​

Messages Context Store SQL Query​

CLI​

Python SDK​

API​

Parameters​

Labels​

Labels List​

CLI​

Python SDK​

API​

Records​

Labels Create​

CLI​

Python SDK​

API​

Parameters​

Records​

Labels Get​

CLI​

Python SDK​

API​

Parameters​

Records​

Labels Update​

CLI​

Python SDK​

API​

Parameters​

Records​

Labels Delete​

Supported entities and actions

Profile

Profile Get

CLI

Python SDK

API

Records

Profile Context Store Search

CLI

Python SDK

API

Parameters

Searchable Fields

Profile Context Store SQL Query

CLI

Python SDK

API

Parameters

Messages

Messages List

CLI

Python SDK

API

Parameters

Records

Meta

Messages Get

CLI

Python SDK

API

Parameters

Records

Messages Create

CLI

Python SDK

API

Parameters

Records

Messages Update

CLI

Python SDK

API

Parameters

Records

Messages Context Store Search

CLI

Python SDK

API

Parameters

Searchable Fields

Messages Context Store SQL Query

CLI

Python SDK

API

Parameters

Labels

Labels List

CLI

Python SDK

API

Records

Labels Create

CLI

Python SDK

API

Parameters

Records

Labels Get

CLI

Python SDK

API

Parameters

Records

Labels Update

CLI

Python SDK

API

Parameters

Records

Labels Delete