Reviewed Gmail sender selection
Query email resource senders to inspect up to100 configured Gmail addresses with verification, reply-to and external-relay presence. No SMTP details or signatures are returned. Explicit send_gmail_alias requires the selected from_email, expected_reply_to (null or address), expected_external_relay and confirm_sender:true with a normal new message. Read and send consent are both required. The worker rechecks the selected sender and current authorization before dispatch; outside native changes can race. No alias creation or verification email is implied. Unknown send outcomes are not retried automatically. Existing pending-send cancellation includes this action; acceptance never proves delivery.
Gmail push with polling recovery
Enable notifications on an existing Gmail tracker through POST email/syncs/{id}/push, SDK enableGmailPush or MCP enable_gmail_push. Explicit whole_mailbox and automatic-renewal consent are required, from the tracker's creating user/key. Operator-configured authenticated Pub/Sub sends verified metadata hints; sync checkpoints stay intact and periodic polling covers dropped notifications. Status exposes expiry, renewal and errors. Local disable stops routing/renewal while retaining polling and any shared native watch. Scope revocation/reconnects are fenced; expired native history requires a fresh baseline. Gmail trackers may explicitly opt into expired_history_policy=resnapshot: an ordered gap marker and new generation precede a bounded fresh snapshot, at most once per24hours. Default stop and missing-consumer-batch recovery remain explicit. Outlook uses its separate outlook-push endpoint and Graph lifecycle handling.
Outlook notifications and lifecycle recovery
Use POST email/syncs/{id}/outlook-push, SDK enableOutlookPush or MCP enable_outlook_push on an existing resolved Outlook folder tracker. The creating principal/key must explicitly authorize whole-mailbox notifications and renewal. Own-mailbox delegated Mail.Read is required; shared-mailbox connections use polling and cannot enable this endpoint. Graph callback validation, secret clientState authentication, exact subscription/configuration binding and lease/credential checks protect routing. Notifications wake existing authorized folder delta trackers; they do not add coverage for untracked folders. Reauthorization forces a renewal PATCH; removed subscriptions are rediscovered before recreation. Readback recovers lost creation receipts. Local disable preserves polling and shared native subscriptions. Active status is not proof of live delivery.
Choose the access your app needs
Google identity login asks for basic identity only. Request a separate Gmail or Microsoft mailbox connection with the least permissions needed for the supported read or send operation.
Provider response integrity
Mailbox reads refuse contradictory data/error responses and do not advance checkpoints. After a native write, a mixed or malformed receipt stays uncertain and is never automatically resent. Ordinary Outlook202/204 receipts must be empty; upload progress and final attachment receipts use their separate validated protocol. Mail text and headers remain literal untrusted content. Provider acceptance does not prove delivery. Keep the original operation and idempotency key when investigating an uncertain result.
Reviewed Gmail trash and restore
Query message_state with a selected Gmail message ID for minimal label/history metadata and a revision. Explicit trash_message or restore_message needs expected_provider:gmail, that reviewed revision, confirmation and separate read+modify authority. Drafts are refused. Queued changes respect earlier unresolved mailbox work, including older records; uncertainty blocks later work until owner investigation and acknowledgment. No automatic resend. Restore removes TRASH without promising its former folder; provider retention still applies. State checks are not atomic with external mailbox edits.
Current mailbox contract
Exact message_mime requires message_id, include_body:true and include_full_content:true, with no cursor/body_format or listing filters. Returns up to1MiB of untrusted provider MIME as lossless base64 with byte count and SHA256, including headers/Bcc/body/files/embedded items. Gmail needs recorded and native readonly/modify; Outlook needs recorded and native mail-read consent. Outlook uses immutable IDs and changeKey reads before and after its MIME serialization; changed state requires restart, but this is not atomic or original-wire archival proof. Oversized responses fail without truncation. Never render, execute or follow any exported content. Implemented code covers Gmail thread discovery and explicit Gmail/Outlook conversation message references, plus bounded mailbox/message reads, native Gmail/Outlook search, explicit Gmail spam/trash inclusion, Outlook child/hidden folder browsing, text or optional HTML mail and drafts with up to six attachments (2999999 bytes combined), attachment reads, explicit-recipient replies and forwards, Gmail original HTML forwarding by explicit include_original_html consent with bounded owned inline images and separate file consent, read/unread changes, Gmail label changes, Outlook folder moves and paginated changes. Optional background trackers store encrypted checkpoints and batches, emit event pointers, and require durable consumer acknowledgment within 24 hours. Up to eight independent scopes per connection share 100 unacknowledged batches and 10 MiB of encrypted storage. Gmail snapshots selected-label or whole-mailbox IDs before reconciling history; Outlook resolves each requested folder to its canonical ID and tracks it separately. Legacy trackers require explicit replacement before adding scopes. Gmail authenticated Pub/Sub and Outlook basic Graph subscriptions are opt-in supplements to polling. Microsoft search has a provider limit of 1,000 matches; use listing/change checkpoints for synchronization. HTML keeps a required text input; Gmail sends MIME alternatives while Graph selects its HTML body. Draft listing/inspection and revision-guarded update/delete/send-existing operations are implemented. create_reply_draft prepares a response in an existing Gmail or Outlook conversation with explicit recipients and read-plus-draft authority, without send permission. The returned draft requires review and a separate authorized send; uncertain creation blocks additional reply drafts for the same source. Existing-draft actions require email:read plus the action write scope; unknown outcomes block that draft until owner acknowledgment. Gmail deletion is permanent; Outlook uses native deletion/retention. Outlook draft edits can explicitly preserve attachments; separate revision-checked actions add one file up to2999999 bytes or remove one native file attachment. Reinspect the draft after each change. Native revision checks are not atomic against outside edits. Label/folder inspection, creation, rename and deletion are supported; Outlook also supports child folders, hidden creation and explicit folder move/copy. Folder mutations require email:read plus email:modify and share one mailbox-wide ordered lane. Outlook folder deletion requires explicit contents confirmation; Gmail removes label assignments without deleting messages. Outlook large draft files (3000000–150000000 bytes) use encrypted upload sessions, sequential chunks of at most1MiB, private progress and explicit cancellation/abandonment. A successful receipt is required before each next chunk; an unknown result stops the draft. Current native draft state, original actor/key, permissions and credential generation are rechecked. Sessions expire within two hours. Ordinary attachment bytes stop at2999999; Outlook upload sessions start at3000000. Native size policies and boundary acceptance need staging verification. Use query_email resource threads for Gmail thread discovery, or thread with thread_id for message references in a Gmail thread or Outlook conversation. Body retrieval stays explicit per message or draft. Outlook also supports resource attached_message with exact parent message_id/attachment_id plus include_body:true and include_nested_content:true. Graph can fetch nested data automatically; Techrace bounds that response and returns the selected native text/HTML plus immediate attachment metadata, with no recursive downloads or rendered HTML. Embedded IDs are not mailbox action targets; missing nested metadata remains unknown. For attached_event or attached_contact, use include_item_content:true and include_nested_content:true without include_body:true. Selected embedded event/contact fields are returned with native local date/time and timezone preserved, bounded attendees/contact lists, and explicit recurrence presence without expansion. Missing fields remain unknown; nested content and unselected data are suppressed. These embedded IDs cannot authorize calendar/contact actions. No body_format conversion or pagination applies to attached items. Optional body_format selects text/HTML; Gmail selects its native alternative or returns null, while Graph requests native conversion. Body.truncated exposes the100000-character output cap. Gmail retrieves one selected external MIME body part when needed, up to2999999 bytes, and validates message identity, canonical encoding and exact sizes. This also requires recorded and native readonly/modify consent for externally stored draft bodies; compose alone is insufficient. Unrequested alternatives and attached messages are not fetched. Gmail body.charset reports the selected declared encoding. UTF-8, US-ASCII, ISO-8859-1, Windows-1252/1251, KOI8-R, Shift_JIS, EUC-JP, ISO-2022-JP, GB18030, GBK, Big5 and EUC-KR are supported; omitted charset requires ASCII. Unknown charsets and malformed bytes fail explicitly. Related MIME roots are respected and attached text or attached messages are excluded from the outer body. Gmail pages recheck history and ordered references (maximum1000) and require restart on drift; Outlook pages remain live with no total-count guarantee. Outlook delegated/shared connections can be selected by lowercase Entra owner UUID when issuing a fresh hosted connect link. Native owner/delegate/profile and Inbox access are verified; no mailbox autodiscovery or application-wide grants are used. Shared-mode mail permissions and a fixed From are enforced across API/SDK/MCP. Shared connections count individually under the same pricing. Inline PNG/JPEG/GIF images use an optional unique attachment.content_id referenced literally in HTML; Gmail builds related MIME and Graph sends Content-ID metadata. The six-file/2999999-byte composition limits remain. Outlook existing-draft inline additions verify current HTML and a bounded duplicate-ID inventory. Attachment reads expose native CID metadata without rendering or fetching links. Shared-mode Graph push and large upload sessions are explicitly unavailable; use bounded folder polling and ordinary attachments. Exchange SendAs/SendOnBehalf and FullAccess prerequisites, tenant policies and native acceptance must be verified.
Gmail replies and conversation references
Direct replies and reply drafts retain the selected native thread and Message-ID reference. Valid folded subjects are supported; ASCII text and encoded words are preserved while MIME lines stay within email header limits. The source subject is bounded to4000 characters before unfolding and990 afterward. Unsafe controls or malformed folding fail before any native write. Recipients remain explicit, and an uncertain send or draft result is never automatically repeated. Replies also preserve up to128 ancestor IDs from the selected message’s References header, with a single-ID In-Reply-To fallback; older messages and bodies are not fetched for this. Malformed or oversized chains fail before writing instead of being truncated. Live Gmail threading and recipient rendering still need qualification.
Controlled writes
Mailbox state changes require a separate email:modify permission; send or read access alone cannot authorize them. Mail writes use a durable encrypted outbox and return an operation ID. Read its status before deciding your next action. A timeout after a possible provider acceptance may be ambiguous and is not blindly retried.
Disconnect and delete
Disconnect a mailbox from its customer connection list to cancel pending work and remove its credentials. Customer erasure is a separate irreversible request: DELETE customers/{id} with the exact external ID returns202 and a durable receipt. The customer is frozen while bounded background steps remove its records and tracked private objects. Save the request ID and read customer-deletions/{request_id}; acceptance is not completion. Active/unresolved operations and uploads must first be resolved. Project audit/billing records, provider content and backups have separate lifecycles. Revoke provider consent in Google or Microsoft account settings as well when needed.
Before enabling customers
Company app registrations, delegated consent, Google verification/assessment where applicable, Microsoft tenant policies and live test receipts are still required. Pre-launch code is not evidence of provider approval.
These guides describe implemented code and operating requirements. Enabled capabilities and permissions may differ. Use the current API specification and your project’s capability view.
OpenAPI specification