How do I install the Gmail full reference skill?

Run npx skillmds@latest add tools-only/gmail-full-reference in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Gmail full reference skill do?

This is the full reference documentation for the Gmail agent connector. It is listed under Coding & Dev Tools on SkillMD.

Is Gmail full reference safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Gmail full reference?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Gmail full reference free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Gmail full reference?

tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Gmail full reference by tools-only — Agent Skill

Name: Gmail full reference
Author: tools-only

Gmail full reference

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
Messages	List, Get, Create, Update
Labels	List, Create, Get, Update, Delete
Drafts	List, Create, Get, Update, Delete
Drafts Send	Create
Threads	List, Get
Messages Trash	Create
Messages Untrash	Create

Profile

Profile Get

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

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"
}'

Records

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

Messages

Messages List

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

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

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

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)

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.

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	The entire email message in RFC 2822 format, base64url encoded
`threadId`	`string`	No	The thread ID to reply to (for threading replies in a conversation)

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.

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

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`

Labels

Labels List

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

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"
}'

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

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)

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

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

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

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

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

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

Drafts

Drafts List

Lists the drafts in the user's mailbox

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

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

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
`message.raw`	`string`	Yes	The draft message in RFC 2822 format, base64url encoded
`message.threadId`	`string`	No	The thread ID for the draft (for threading in a conversation)

Records

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

Drafts Get

Gets the specified draft including its message content

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)

Records

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

Drafts Update

Replaces a draft's content with the specified message content

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
`message.raw`	`string`	Yes	The draft message in RFC 2822 format, base64url encoded
`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

Records

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

Drafts Delete

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

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 Send

Drafts Send Create

Sends the specified existing draft to its recipients

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

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

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

Records

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

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

Threads Get

Gets the specified thread including all messages in the conversation

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)

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`

Messages Trash

Messages Trash Create

Moves the specified message to the trash

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

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

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

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`

Gmail full reference

File contents

Gmail full reference

Supported entities and actions

Profile

Profile Get

Python SDK

API

Records

Messages

Messages List

Python SDK

API

Parameters

Records

Meta

Messages Get

Python SDK

API

Parameters

Records

Messages Create

Python SDK

API

Parameters

Records

Messages Update

Python SDK

API

Parameters

Records

Labels

Labels List

Python SDK

API

Records

Labels Create

Python SDK

API

Parameters

Records

Labels Get

Python SDK

API

Parameters

Records

Labels Update

Python SDK

API

Parameters

Records

Labels Delete

Python SDK

API

Parameters

Drafts

Drafts List

Python SDK

API

Parameters

Records

Meta

Drafts Create

Python SDK

API

Parameters

Records

Drafts Get

Python SDK

API

Parameters

Records

Drafts Update

Python SDK

API

Parameters

Records

Drafts Delete

Python SDK

API