AgentMail

Return metadata for up to 500 messages from one inbox in a single request. Compare count with limit to detect missing or restricted IDs. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.

Atomically add or remove the same labels on up to 50 messages in one inbox. Missing or restricted message IDs are omitted from the result. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.

Mark a pending Agent Drive file ready after its bytes have been PUT to the presigned URL returned by CREATE_FILE. AgentMail verifies the exact declared size and SHA-256; calling this before a successful upload returns a conflict. Only a key with file_read or the key that created the file can complete it. Agent Drive is a US-production-only Labs feature.

Record whether Agent Armor's completed verdict on a message was correct. A message accepts up to 20 feedback records.

Create a one-off or recurring event on a US-only inbox calendar. client_id makes retries safe; send_invites emails attendees and consumes send limits.

Create a draft, optionally scheduling its automatic delivery with send_at.

Initialize a pending Agent Drive file and return instructions for a direct storage upload. This does not upload bytes: PUT the exact bytes to the credential-sensitive presigned URL with every returned header unchanged and without the AgentMail API key, then call COMPLETE_FILE_UPLOAD. Identical requests are retry-safe. Pending files consume Drive quota immediately and expire after one day if incomplete; call DELETE_FILE when abandoning an upload. Agent Drive is a US-production-only Labs feature.

Create a new AgentMail inbox via API. Returns the inbox_id and email address for sending/receiving messages. Use when provisioning new inboxes for agents or workflows.

Create an inbox-scoped bearer key and return its one-time secret. Omitting permissions grants all permissions available within the inbox scope.

Create an inbox inside an explicitly selected AgentMail pod, optionally choosing its address, initial status, idempotency ID, and metadata.

Create or resume a polling webhook scoped to one inbox. The inbox comes from the path, so organization selector lists are not accepted. AgentMail's polling guide currently says polling is US-only even though the API reference lists an EU server; follow the guide and do not assume EU support. The response contains a one-time credential-sensitive polling token; store it securely and never log or expose it.

Create a regular webhook scoped to one AgentMail inbox for a non-empty set of event types. The response contains a credential-sensitive signature secret; never log or expose it.