Gmail

Run a valid gmail.add_email_label call through the same SDK surface used by every toolkit.

Minimal tool call

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const output = await eyeball.tools.run(
  "gmail.add_email_label",
  {
  "messageId": "example_messageId",
  "labelId": "example_labelId",
  "operation": "add"
},
  { userId: "demo_user",
  idempotencyKey: "docs:gmail.add_email_label:demo-1" },
);
console.log(output);

The model receives canonical output. Your application retains the execution envelope through tools.execute or the execution APIs when it needs IDs, status, versions, and latency.

Supported canonical tools

Tool	Purpose	Execution	Effect	Version
`gmail.add_email_label`	Apply a label, category, or destination folder to an existing email message. Use this to organize mail without changing its content; repeating the same operation has no additional effect.	sync or async	mutation	`1.0.0`
`gmail.create_draft`	Create an unsent email draft in the connected mailbox. Use this when a person or later workflow should review or send the content; this does not deliver a message to recipients.	sync or async	mutation	`1.1.0`
`gmail.get_email`	Retrieve one email message with normalized headers, body, labels, and attachment metadata. Use this after obtaining a message identifier; it does not download attachment content.	sync or async	read	`1.0.0`
`gmail.list_emails`	List email messages from a mailbox, folder, or label with portable filters and pagination. Use this to browse messages; use search_emails when a provider query expression is the primary selector.	sync or async	read	`1.0.0`
`gmail.list_threads`	List email conversation threads and their latest state with portable filters and pagination. Use this when conversation grouping is more useful than individual message rows.	sync or async	read	`1.0.0`
`gmail.reply_to_email`	Reply within an existing email message or conversation thread. Use this instead of send_email when preserving reply headers and thread context matters; verify reply-all recipients before sending.	sync or async	mutation	`1.1.0`
`gmail.search_emails`	Search mailbox content using a provider-supported query expression and return normalized email summaries. Use this for full-text or provider query syntax; query portability depends on the connected provider.	sync or async	read	`1.0.0`
`gmail.send_email`	Send a new email from the connected email account. Use this for a new conversation, not a reply to an existing message or thread. This sends content to external recipients; verify recipients, subject, and body first.	sync or async	mutation	`1.1.0`

Only the rows above are implemented. A capability tool omitted by this manifest returns not_supported; eyeball never synthesizes provider parity.

Supported canonical triggers

Trigger	Purpose	Ingestion	Version
`gmail.email_received`	Emit a canonical event when a new email reaches the connected mailbox and matches the configured portable filters.	polling	`1.0.0`

Subscribe with eyeball.subscriptions.create. Trigger events arrive through the signed webhook engine as trigger.<toolkit>.<name>.

Input and output schemas

gmail.add_email_label

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:add_email_label:1.0.0:gmail",
  "type": "object",
  "description": "Target email and label, category, or folder operation to apply.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "labelId"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the email message to update.",
      "minLength": 1
    },
    "labelId": {
      "type": "string",
      "description": "Provider identifier or exact name of the label, category, or folder.",
      "minLength": 1
    },
    "operation": {
      "type": "string",
      "description": "Whether to add a label/category or move the email to a folder.",
      "enum": [
        "add",
        "move"
      ],
      "default": "add"
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:add_email_label:output:1.0.0:gmail",
  "type": "object",
  "description": "Result of applying the requested mailbox organization operation.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "labelId",
    "applied"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the updated email message.",
      "minLength": 1
    },
    "labelId": {
      "type": "string",
      "description": "Provider identifier or name of the applied label, category, or folder.",
      "minLength": 1
    },
    "applied": {
      "type": "boolean",
      "description": "Whether the requested organization state is now in effect."
    }
  }
}

gmail.create_draft

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:create_draft:1.1.0:gmail",
  "type": "object",
  "description": "Recipients, content, and staged attachments to save as an email draft.",
  "additionalProperties": false,
  "required": [
    "body"
  ],
  "properties": {
    "to": {
      "type": "array",
      "description": "Primary recipient email addresses saved on the draft.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "cc": {
      "type": "array",
      "description": "Carbon-copy recipient email addresses saved on the draft.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "bcc": {
      "type": "array",
      "description": "Blind-carbon-copy recipient email addresses saved on the draft.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "subject": {
      "type": "string",
      "description": "Subject line saved on the draft.",
      "maxLength": 998
    },
    "body": {
      "type": "string",
      "description": "Complete body in the format selected by bodyFormat.",
      "minLength": 1
    },
    "bodyFormat": {
      "type": "string",
      "description": "Serialization format of the body content.",
      "enum": [
        "text",
        "html"
      ],
      "default": "text"
    },
    "replyTo": {
      "type": "string",
      "format": "email",
      "description": "Address recipients should use if the draft is later sent and replied to."
    },
    "attachments": {
      "type": "array",
      "description": "Previously staged Eyeball files to attach.",
      "maxItems": 25,
      "items": {
        "description": "A staged file reference that the provider can attach.",
        "anyOf": [
          {
            "type": "object",
            "description": "Preferred staged-file reference shape.",
            "additionalProperties": false,
            "required": [
              "fileId"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball file_* identifier returned by POST /v1/files.",
                "pattern": "^file_[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
              },
              "name": {
                "type": "string",
                "description": "Optional recipient-visible name overriding staged metadata.",
                "minLength": 1
              },
              "mimeType": {
                "type": "string",
                "description": "Optional MIME type overriding staged metadata for delivery.",
                "minLength": 1
              }
            }
          },
          {
            "type": "object",
            "description": "Deprecated 1.0 staged-file reference retained for compatibility.",
            "additionalProperties": false,
            "required": [
              "fileId",
              "fileName"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball identifier of the previously staged file.",
                "minLength": 1
              },
              "fileName": {
                "type": "string",
                "description": "Deprecated recipient-visible name; use name in new calls.",
                "minLength": 1
              },
              "contentType": {
                "type": "string",
                "description": "Deprecated MIME type; use mimeType in new calls.",
                "minLength": 1
              }
            }
          }
        ]
      }
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:create_draft:output:1.1.0:gmail",
  "type": "object",
  "description": "Provider identifiers for the newly created unsent draft.",
  "additionalProperties": false,
  "required": [
    "draftId"
  ],
  "properties": {
    "draftId": {
      "type": "string",
      "description": "Provider identifier of the created draft resource.",
      "minLength": 1
    },
    "messageId": {
      "type": "string",
      "description": "Provider message identifier associated with the draft when available.",
      "minLength": 1
    },
    "threadId": {
      "type": "string",
      "description": "Provider identifier of the conversation thread when available.",
      "minLength": 1
    }
  }
}

gmail.get_email

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:get_email:1.0.0:gmail",
  "type": "object",
  "description": "Identifier and content-selection options for one email.",
  "additionalProperties": false,
  "required": [
    "messageId"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the email message to retrieve.",
      "minLength": 1
    },
    "includeBody": {
      "type": "boolean",
      "description": "Whether to include the normalized message body in the response.",
      "default": true
    },
    "includeAttachmentMetadata": {
      "type": "boolean",
      "description": "Whether to include attachment identifiers and metadata.",
      "default": true
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:get_email:output:1.0.0:gmail",
  "type": "object",
  "description": "Normalized content and metadata for one email message.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "from",
    "to",
    "subject",
    "receivedAt"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the email message.",
      "minLength": 1
    },
    "threadId": {
      "type": "string",
      "description": "Provider identifier of the containing conversation thread.",
      "minLength": 1
    },
    "from": {
      "type": "string",
      "format": "email",
      "description": "Sender email address."
    },
    "to": {
      "type": "array",
      "description": "Primary recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "cc": {
      "type": "array",
      "description": "Carbon-copy recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "bcc": {
      "type": "array",
      "description": "Blind-carbon-copy recipient email addresses visible to the connection.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "subject": {
      "type": "string",
      "description": "Email subject exactly as stored by the provider."
    },
    "sentAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp supplied by the sender or provider."
    },
    "receivedAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the mailbox received the email."
    },
    "body": {
      "type": "object",
      "description": "Normalized email body when includeBody is true and content is available.",
      "additionalProperties": false,
      "required": [
        "format",
        "content"
      ],
      "properties": {
        "format": {
          "type": "string",
          "description": "Serialization format of the returned body.",
          "enum": [
            "text",
            "html"
          ]
        },
        "content": {
          "type": "string",
          "description": "Complete normalized email body content."
        }
      }
    },
    "headers": {
      "type": "array",
      "description": "Ordered message headers exposed by the provider.",
      "items": {
        "type": "object",
        "description": "One email header name and value.",
        "additionalProperties": false,
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Case-preserving email header name.",
            "minLength": 1
          },
          "value": {
            "type": "string",
            "description": "Unfolded email header value."
          }
        }
      }
    },
    "attachments": {
      "type": "array",
      "description": "Metadata for files attached to the email; file content is not included.",
      "items": {
        "type": "object",
        "description": "Metadata identifying one email attachment.",
        "additionalProperties": false,
        "required": [
          "attachmentId",
          "fileName"
        ],
        "properties": {
          "attachmentId": {
            "type": "string",
            "description": "Provider-stable identifier for the attachment.",
            "minLength": 1
          },
          "fileName": {
            "type": "string",
            "description": "Original attachment file name.",
            "minLength": 1
          },
          "contentType": {
            "type": "string",
            "description": "MIME content type reported for the attachment.",
            "minLength": 1
          },
          "sizeBytes": {
            "type": "integer",
            "description": "Attachment size in bytes when reported by the provider.",
            "minimum": 0
          }
        }
      }
    },
    "labelIds": {
      "type": "array",
      "description": "Provider label, category, or folder identifiers on the email.",
      "items": {
        "type": "string",
        "description": "Provider identifier of an applied label, category, or folder.",
        "minLength": 1
      }
    },
    "draft": {
      "type": "boolean",
      "description": "Whether the retrieved message is an unsent draft."
    }
  }
}

gmail.list_emails

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_emails:1.0.0:gmail",
  "type": "object",
  "description": "Mailbox location, filters, and pagination for listing email messages.",
  "additionalProperties": false,
  "properties": {
    "mailboxId": {
      "type": "string",
      "description": "Mailbox identifier; omit to use the connected account's default mailbox.",
      "minLength": 1
    },
    "folderId": {
      "type": "string",
      "description": "Folder identifier used to restrict the mailbox listing.",
      "minLength": 1
    },
    "labelIds": {
      "type": "array",
      "description": "Labels or categories every returned email should have.",
      "items": {
        "type": "string",
        "description": "Provider label or category identifier.",
        "minLength": 1
      }
    },
    "from": {
      "type": "string",
      "format": "email",
      "description": "Return only emails from this sender address."
    },
    "to": {
      "type": "string",
      "format": "email",
      "description": "Return only emails addressed to this recipient."
    },
    "subject": {
      "type": "string",
      "description": "Case-insensitive subject text to match.",
      "minLength": 1
    },
    "receivedAfter": {
      "type": "string",
      "format": "date-time",
      "description": "Return emails received at or after this RFC 3339 timestamp."
    },
    "receivedBefore": {
      "type": "string",
      "format": "date-time",
      "description": "Return emails received before this RFC 3339 timestamp."
    },
    "unreadOnly": {
      "type": "boolean",
      "description": "When true, return only unread emails.",
      "default": false
    },
    "hasAttachments": {
      "type": "boolean",
      "description": "When supplied, filter by whether an email has attachments."
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of emails to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous email page.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_emails:output:1.0.0:gmail",
  "type": "object",
  "description": "One page of email summaries and an optional continuation token.",
  "additionalProperties": false,
  "required": [
    "emails"
  ],
  "properties": {
    "emails": {
      "type": "array",
      "description": "Email summaries in provider-defined mailbox order.",
      "items": {
        "type": "object",
        "description": "Compact mailbox metadata for one email message.",
        "additionalProperties": false,
        "required": [
          "messageId",
          "from",
          "to",
          "subject",
          "receivedAt",
          "unread",
          "hasAttachments"
        ],
        "properties": {
          "messageId": {
            "type": "string",
            "description": "Provider identifier of the email message.",
            "minLength": 1
          },
          "threadId": {
            "type": "string",
            "description": "Provider identifier of the containing conversation thread.",
            "minLength": 1
          },
          "from": {
            "type": "string",
            "format": "email",
            "description": "Sender email address."
          },
          "to": {
            "type": "array",
            "description": "Primary recipient email addresses.",
            "items": {
              "type": "string",
              "format": "email",
              "description": "A syntactically valid email address."
            }
          },
          "subject": {
            "type": "string",
            "description": "Email subject exactly as stored by the provider."
          },
          "snippet": {
            "type": "string",
            "description": "Short provider-generated preview of the email body."
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the mailbox received the email."
          },
          "unread": {
            "type": "boolean",
            "description": "Whether the email is currently marked unread."
          },
          "hasAttachments": {
            "type": "boolean",
            "description": "Whether the email includes at least one attachment."
          },
          "labelIds": {
            "type": "array",
            "description": "Provider label, category, or folder identifiers on the email.",
            "items": {
              "type": "string",
              "description": "Provider identifier of an applied label, category, or folder.",
              "minLength": 1
            }
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of emails; absent when the result is complete.",
      "minLength": 1
    }
  }
}

gmail.list_threads

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_threads:1.0.0:gmail",
  "type": "object",
  "description": "Mailbox filters and pagination for listing conversation threads.",
  "additionalProperties": false,
  "properties": {
    "mailboxId": {
      "type": "string",
      "description": "Mailbox identifier; omit to use the connected account's default mailbox.",
      "minLength": 1
    },
    "labelIds": {
      "type": "array",
      "description": "Labels or categories every returned thread should have.",
      "items": {
        "type": "string",
        "description": "Provider label or category identifier.",
        "minLength": 1
      }
    },
    "participantAddresses": {
      "type": "array",
      "description": "Return threads containing at least one of these participant addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "receivedAfter": {
      "type": "string",
      "format": "date-time",
      "description": "Return threads updated at or after this RFC 3339 timestamp."
    },
    "receivedBefore": {
      "type": "string",
      "format": "date-time",
      "description": "Return threads updated before this RFC 3339 timestamp."
    },
    "unreadOnly": {
      "type": "boolean",
      "description": "When true, return only threads containing unread messages.",
      "default": false
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of threads to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous thread page.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_threads:output:1.0.0:gmail",
  "type": "object",
  "description": "One page of normalized conversation threads and an optional continuation token.",
  "additionalProperties": false,
  "required": [
    "threads"
  ],
  "properties": {
    "threads": {
      "type": "array",
      "description": "Conversation threads in provider-defined mailbox order.",
      "items": {
        "type": "object",
        "description": "Summary and latest state for one email conversation thread.",
        "additionalProperties": false,
        "required": [
          "threadId",
          "participantAddresses",
          "messageCount",
          "latestMessageAt",
          "unread"
        ],
        "properties": {
          "threadId": {
            "type": "string",
            "description": "Provider identifier of the conversation thread.",
            "minLength": 1
          },
          "subject": {
            "type": "string",
            "description": "Most representative or latest subject for the thread."
          },
          "participantAddresses": {
            "type": "array",
            "description": "Distinct email addresses participating in the thread.",
            "items": {
              "type": "string",
              "format": "email",
              "description": "A syntactically valid email address."
            }
          },
          "messageCount": {
            "type": "integer",
            "description": "Number of messages currently in the thread.",
            "minimum": 1
          },
          "latestMessageAt": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp of the latest message in the thread."
          },
          "snippet": {
            "type": "string",
            "description": "Short provider-generated preview of the latest thread content."
          },
          "unread": {
            "type": "boolean",
            "description": "Whether the thread contains at least one unread message."
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of threads; absent when the result is complete.",
      "minLength": 1
    }
  }
}

gmail.reply_to_email

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:reply_to_email:1.1.0:gmail",
  "type": "object",
  "description": "Target message, reply content, recipient behavior, and staged attachments.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "body"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the email being replied to.",
      "minLength": 1
    },
    "body": {
      "type": "string",
      "description": "Complete body in the format selected by bodyFormat.",
      "minLength": 1
    },
    "bodyFormat": {
      "type": "string",
      "description": "Serialization format of the body content.",
      "enum": [
        "text",
        "html"
      ],
      "default": "text"
    },
    "replyAll": {
      "type": "boolean",
      "description": "When true, include the original sender and recipients supported by the provider.",
      "default": false
    },
    "to": {
      "type": "array",
      "description": "Explicit primary reply recipients, overriding provider-derived recipients.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "cc": {
      "type": "array",
      "description": "Explicit carbon-copy reply recipients.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "bcc": {
      "type": "array",
      "description": "Explicit blind-carbon-copy reply recipients.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "attachments": {
      "type": "array",
      "description": "Previously staged Eyeball files to attach.",
      "maxItems": 25,
      "items": {
        "description": "A staged file reference that the provider can attach.",
        "anyOf": [
          {
            "type": "object",
            "description": "Preferred staged-file reference shape.",
            "additionalProperties": false,
            "required": [
              "fileId"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball file_* identifier returned by POST /v1/files.",
                "pattern": "^file_[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
              },
              "name": {
                "type": "string",
                "description": "Optional recipient-visible name overriding staged metadata.",
                "minLength": 1
              },
              "mimeType": {
                "type": "string",
                "description": "Optional MIME type overriding staged metadata for delivery.",
                "minLength": 1
              }
            }
          },
          {
            "type": "object",
            "description": "Deprecated 1.0 staged-file reference retained for compatibility.",
            "additionalProperties": false,
            "required": [
              "fileId",
              "fileName"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball identifier of the previously staged file.",
                "minLength": 1
              },
              "fileName": {
                "type": "string",
                "description": "Deprecated recipient-visible name; use name in new calls.",
                "minLength": 1
              },
              "contentType": {
                "type": "string",
                "description": "Deprecated MIME type; use mimeType in new calls.",
                "minLength": 1
              }
            }
          }
        ]
      }
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:reply_to_email:output:1.1.0:gmail",
  "type": "object",
  "description": "Identifiers and accepted recipients for the sent reply.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "acceptedRecipients"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the created email message.",
      "minLength": 1
    },
    "threadId": {
      "type": "string",
      "description": "Provider identifier of the conversation thread when available.",
      "minLength": 1
    },
    "acceptedRecipients": {
      "type": "array",
      "description": "Recipient addresses accepted by the provider for delivery.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    }
  }
}

gmail.search_emails

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:search_emails:1.0.0:gmail",
  "type": "object",
  "description": "Mailbox query and pagination for an email search.",
  "additionalProperties": false,
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "Provider-supported mailbox search expression or full-text query.",
      "minLength": 1
    },
    "mailboxId": {
      "type": "string",
      "description": "Mailbox identifier; omit to search the connected account's default mailbox.",
      "minLength": 1
    },
    "folderId": {
      "type": "string",
      "description": "Folder identifier used to restrict the search when supported.",
      "minLength": 1
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of email search results to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous email search result page.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:search_emails:output:1.0.0:gmail",
  "type": "object",
  "description": "One page of matching email summaries and an optional continuation token.",
  "additionalProperties": false,
  "required": [
    "emails"
  ],
  "properties": {
    "emails": {
      "type": "array",
      "description": "Email summaries matching the provider query.",
      "items": {
        "type": "object",
        "description": "Compact mailbox metadata for one email message.",
        "additionalProperties": false,
        "required": [
          "messageId",
          "from",
          "to",
          "subject",
          "receivedAt",
          "unread",
          "hasAttachments"
        ],
        "properties": {
          "messageId": {
            "type": "string",
            "description": "Provider identifier of the email message.",
            "minLength": 1
          },
          "threadId": {
            "type": "string",
            "description": "Provider identifier of the containing conversation thread.",
            "minLength": 1
          },
          "from": {
            "type": "string",
            "format": "email",
            "description": "Sender email address."
          },
          "to": {
            "type": "array",
            "description": "Primary recipient email addresses.",
            "items": {
              "type": "string",
              "format": "email",
              "description": "A syntactically valid email address."
            }
          },
          "subject": {
            "type": "string",
            "description": "Email subject exactly as stored by the provider."
          },
          "snippet": {
            "type": "string",
            "description": "Short provider-generated preview of the email body."
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the mailbox received the email."
          },
          "unread": {
            "type": "boolean",
            "description": "Whether the email is currently marked unread."
          },
          "hasAttachments": {
            "type": "boolean",
            "description": "Whether the email includes at least one attachment."
          },
          "labelIds": {
            "type": "array",
            "description": "Provider label, category, or folder identifiers on the email.",
            "items": {
              "type": "string",
              "description": "Provider identifier of an applied label, category, or folder.",
              "minLength": 1
            }
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of email search results; absent when the result is complete.",
      "minLength": 1
    }
  }
}

gmail.send_email

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:send_email:1.1.0:gmail",
  "type": "object",
  "description": "Recipients, content, and staged attachments for a new email.",
  "additionalProperties": false,
  "required": [
    "to",
    "subject",
    "body"
  ],
  "properties": {
    "to": {
      "type": "array",
      "description": "Primary recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      },
      "minItems": 1
    },
    "cc": {
      "type": "array",
      "description": "Carbon-copy recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "bcc": {
      "type": "array",
      "description": "Blind-carbon-copy recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "subject": {
      "type": "string",
      "description": "Subject line shown to recipients.",
      "minLength": 1,
      "maxLength": 998
    },
    "body": {
      "type": "string",
      "description": "Complete body in the format selected by bodyFormat.",
      "minLength": 1
    },
    "bodyFormat": {
      "type": "string",
      "description": "Serialization format of the body content.",
      "enum": [
        "text",
        "html"
      ],
      "default": "text"
    },
    "replyTo": {
      "type": "string",
      "format": "email",
      "description": "Address recipients should use when replying instead of the sender."
    },
    "attachments": {
      "type": "array",
      "description": "Previously staged Eyeball files to attach.",
      "maxItems": 25,
      "items": {
        "description": "A staged file reference that the provider can attach.",
        "anyOf": [
          {
            "type": "object",
            "description": "Preferred staged-file reference shape.",
            "additionalProperties": false,
            "required": [
              "fileId"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball file_* identifier returned by POST /v1/files.",
                "pattern": "^file_[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
              },
              "name": {
                "type": "string",
                "description": "Optional recipient-visible name overriding staged metadata.",
                "minLength": 1
              },
              "mimeType": {
                "type": "string",
                "description": "Optional MIME type overriding staged metadata for delivery.",
                "minLength": 1
              }
            }
          },
          {
            "type": "object",
            "description": "Deprecated 1.0 staged-file reference retained for compatibility.",
            "additionalProperties": false,
            "required": [
              "fileId",
              "fileName"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball identifier of the previously staged file.",
                "minLength": 1
              },
              "fileName": {
                "type": "string",
                "description": "Deprecated recipient-visible name; use name in new calls.",
                "minLength": 1
              },
              "contentType": {
                "type": "string",
                "description": "Deprecated MIME type; use mimeType in new calls.",
                "minLength": 1
              }
            }
          }
        ]
      }
    },
    "x_provider": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "gmail": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "sendAs": {
              "type": "string",
              "format": "email",
              "description": "A verified Gmail send-as identity."
            }
          }
        }
      }
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:send_email:output:1.1.0:gmail",
  "type": "object",
  "description": "Identifiers and accepted recipients for the newly sent email.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "acceptedRecipients"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the created email message.",
      "minLength": 1
    },
    "threadId": {
      "type": "string",
      "description": "Provider identifier of the conversation thread when available.",
      "minLength": 1
    },
    "acceptedRecipients": {
      "type": "array",
      "description": "Recipient addresses accepted by the provider for delivery.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    }
  }
}

Trigger payload schemas

gmail.email_received

Payload schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:email_received:payload:1.0.0:gmail",
  "type": "object",
  "description": "Canonical metadata for the newly received email.",
  "additionalProperties": false,
  "required": [
    "id",
    "from",
    "to",
    "subject",
    "snippet",
    "threadId",
    "receivedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Provider-stable identifier of the received email.",
      "minLength": 1
    },
    "from": {
      "type": "string",
      "format": "email",
      "description": "Normalized sender email address."
    },
    "to": {
      "type": "array",
      "description": "Normalized recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "subject": {
      "type": "string",
      "description": "Subject line, or an empty string when absent."
    },
    "snippet": {
      "type": "string",
      "description": "Short normalized preview of the email body."
    },
    "threadId": {
      "type": "string",
      "description": "Provider-stable conversation thread identifier.",
      "minLength": 1
    },
    "receivedAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the mailbox received the email."
    },
    "x_provider": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "gmail": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "historyId",
            "labelIds"
          ],
          "properties": {
            "historyId": {
              "type": "string",
              "minLength": 1
            },
            "labelIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      }
    }
  }
}

Authentication

Property	Value
Auth class	`oauth2`
Required scopes	`https://www.googleapis.com/auth/gmail.modify`
Optional scopes	`https://www.googleapis.com/auth/gmail.send`
Credential fields	None

Credentials are resolved inside the executor by CredentialProvider. They never belong in tool input, x_provider, model context, logs, or execution output.

Provider-specific extensions

`gmail.send_email` input

input.x_provider.gmail accepts:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "sendAs": {
      "type": "string",
      "format": "email",
      "description": "A verified Gmail send-as identity."
    }
  }
}

`gmail.email_received` trigger payload

payload.x_provider.gmail may contain:

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "historyId",
    "labelIds"
  ],
  "properties": {
    "historyId": {
      "type": "string",
      "minLength": 1
    },
    "labelIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  }
}

Provider differences may appear only under x_provider.gmail and only when the schema above declares them.

Sync and async behavior

All tools are synchronous by nature, but callers may choose mode: "async" to queue them.

Mutations require a stable Idempotency-Key. The TypeScript SDK accepts it as idempotencyKey; it is never part of the JSON request body.

REST example

curl "$EYEBALL_EXECUTOR_URL/v1/execute" \
  -H "Authorization: Bearer $EYEBALL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: docs:gmail.add_email_label:demo-1' \
  --data '{"tool":"gmail.add_email_label","userId":"demo_user","input":{"messageId":"example_messageId","labelId":"example_labelId","operation":"add"},"mode":"sync"}'

Point EYEBALL_EXECUTOR_URL at a mock-configured executor to run through the real catalog, validation, credential seam, adapter, normalized errors, and execution records with no Gmail account. Mock selection changes the executor endpoint and trusted provider base-URL configuration, never the execute request.

Limitations

This page describes the manifest's explicit P0 subset, not every operation offered by the provider.
Provider account policy, consent UI, quota details, and current wire compatibility still require a real-provider certification pass.
Fields outside the canonical schemas and declared x_provider extensions are rejected.

Versions

Contract	Version
Runtime catalog	`1.1`
Manifest catalog	`1.1`
Manifest schema	`1.0`
Source	`activepieces-bridge`
Tier	`P0`
Capabilities	`email`

Use Testing with mocks to exercise this toolkit before connecting a live provider account.

Minimal tool call

Supported canonical tools

Supported canonical triggers

Input and output schemas

Trigger payload schemas

Authentication

Provider-specific extensions

`gmail.send_email` input

`gmail.email_received` trigger payload

Sync and async behavior

REST example

Mock support

Limitations

Versions

Next