Gmail filters both server-side via search operators, so neither is emulated here. Note the date
bound is approximate at second granularity — see GmailBoundSeconds.
ProtectedProviderReturns the name of this provider for use in error messages. Override in subclasses to provide a more descriptive name.
Convenience gate: true when this provider supports inbound push in ANY form
(subscription-managed or inbound-parse), false otherwise. Lets callers cleanly
short-circuit — if (provider.SupportsPush) { ... } — instead of probing individual
operations.
Derived from GetSubscriptionCapabilities so it stays in lockstep with actual
capability: providers that support push return capabilities and thereby report
SupportsPush === true for free; providers that don't return undefined and report
false. Subclasses normally do NOT override this — override
GetSubscriptionCapabilities instead.
Archives a message (removes INBOX label in Gmail)
Parameters for archiving the message
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Cancels (deletes) a Google Calendar event via calendar.events.delete.
Optionalcredentials: GmailCredentialsDeletes the event with sendUpdates: 'all': from the organizer's calendar that cancels it for
everyone; from an attendee's it removes that copy only. Google has no cancellation comment, so
Comment is not sent. An event already gone (404 or 410) counts as cancelled.
Optionalcredentials: GmailCredentialsCreates a Google Calendar event via calendar.events.insert.
Optionalcredentials: GmailCredentialsCreates a draft message in Gmail
Parameters for creating a draft
Optionalcredentials: GmailCredentialsOptional credentials override for this request.
If not provided, uses environment variables.
Set credentials.disableEnvironmentFallback = true to require explicit credentials.
Inserts an event and sends invitations to its attendees (sendUpdates: 'all').
Optionalcredentials: GmailCredentialsCreates a Gmail mailbox watch so change notifications are published to a Google Cloud Pub/Sub topic. Gmail delivers via Pub/Sub (not an HTTP endpoint), so CreateSubscriptionParams.NotificationUrl is NOT required here.
What to watch; ContextData.topicName (Pub/Sub topic) is REQUIRED
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Promise
Gmail API scope: https://www.googleapis.com/auth/gmail.readonly (or broader, e.g. gmail.modify).
Deletes a message from Gmail
Parameters for deleting the message
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Stops the Gmail mailbox watch (users.stop). Idempotent from the consumer's
perspective: a 404 / not-found is treated as success.
SubscriptionID is the mailbox userId whose watch to stop
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Promise
Gmail API scope: https://www.googleapis.com/auth/gmail.readonly (or broader).
Downloads an attachment from a message
Parameters for downloading the attachment
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Suggests optimal meeting times across attendees within a time window. Override in subclasses that support this operation.
Optionalcredentials: ProviderCredentialsBaseForward a message using Gmail API
Parameters for forwarding a message
Optionalcredentials: GmailCredentialsOptional credentials override for this request.
If not provided, uses environment variables.
Set credentials.disableEnvironmentFallback = true to require explicit credentials.
Reads one event with each attendee's response.
Optionalcredentials: GmailCredentialsLists calendar events from Google Calendar v3 (calendar.events.list).
Optionalcredentials: GmailCredentialsQueries free/busy schedule intervals across one or more Google Calendars
via calendar.freebusy.query.
Optionalcredentials: GmailCredentialsGets messages from Gmail
Parameters for fetching messages
Optionalcredentials: GmailCredentialsOptional credentials override for this request.
If not provided, uses environment variables.
Set credentials.disableEnvironmentFallback = true to require explicit credentials.
Gets a single message by ID
Parameters for retrieving the message
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Returns Gmail's subscription capabilities. Gmail mailbox watches expire after ~7 days (so they must be re-watched), notify only on new/changed mail, deliver via Pub/Sub (no endpoint validation handshake), are programmatically managed, and are HINT-mode (the payload carries only a historyId, never the message inline).
Returns the list of operations supported by the Gmail provider. Gmail supports all mailbox and Google Calendar v3 operations.
Lists attachments on a message
Parameters for listing attachments
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Lists Gmail labels (Gmail's equivalent of folders)
Parameters for listing labels
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Marks messages as read or unread
Parameters for marking messages
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Moves a message to a different label (Gmail's equivalent of folders) In Gmail, moving is done by adding/removing labels
Parameters for moving the message
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Parses an inbound Gmail Pub/Sub push notification. Pure: no network, never throws on
hostile/garbage input (returns Success: false + a 400 suggested status instead).
The Pub/Sub push body is JSON of the shape
{ message: { data: <base64 of JSON {emailAddress, historyId}>, messageId, publishTime }, subscription }.
This is HINT-mode: the decoded payload only carries a historyId, so
NormalizedNotification.MessageIDs is empty and the consumer must re-fetch the
changed messages via the Gmail history API / GetMessages.
NOTE: no cryptographic signature scheme is applied here, so ParseNotificationResult.SignatureValid is left undefined. Pub/Sub push authenticity is normally established via OIDC token verification on the push endpoint, which is out of scope for this pure parser (the consumer's HTTP layer owns it).
Transport-neutral capture of the inbound webhook request
Optional_credentials: GmailCredentialsPromise
Renews a Gmail mailbox watch by re-issuing users.watch for the same mailbox. Gmail
has no distinct renewal call — re-watching before the ~7-day expiry is the renewal.
SubscriptionID is the mailbox userId; ContextData.topicName is REQUIRED
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Promise
Gmail API scope: https://www.googleapis.com/auth/gmail.readonly (or broader).
Reply to a message using Gmail API
Parameters for replying to a message
Optionalcredentials: GmailCredentialsOptional credentials override for this request.
If not provided, uses environment variables.
Set credentials.disableEnvironmentFallback = true to require explicit credentials.
Responds to a Google Calendar event invitation by updating the attendee's responseStatus.
Optionalcredentials: GmailCredentialsSearches messages using Gmail's search syntax
Parameters for searching messages
Optionalcredentials: GmailCredentialsOptional credentials override for this request
Sends a single message using the Gmail API
The message to send
Optionalcredentials: GmailCredentialsOptional credentials override for this request.
If not provided, uses environment variables.
Set credentials.disableEnvironmentFallback = true to require explicit credentials.
Checks if this provider supports a specific operation.
The operation to check
true if the operation is supported
Incremental sync through events.list. With no token, a full read of the window (open-ended when
the window is not given); with one, only what changed. Recurring events are expanded
(singleEvents), on every request, since Google wants the same parameters on the incremental
reads as on the full one. Pages are followed until the nextSyncToken. An expired token is a
410 Gone: that comes back as ResyncRequired.
Optionalcredentials: GmailCredentialsUpdates an existing Google Calendar event via calendar.events.patch.
Optionalcredentials: GmailCredentialsPatches the given fields and sends the update to attendees.
Optionalcredentials: GmailCredentialsVerifies whether the active Gmail / Google Workspace credential has access to the specified mailbox and/or calendar.
Optionalcredentials: GmailCredentials
Base class for all communication providers. Each provider sub-classes this base class and implements functionality specific to the provider.
Remarks
All methods accept an optional
credentialsparameter that allows per-request credential overrides. When credentials are provided, they take precedence over environment variables. Setcredentials.disableEnvironmentFallback = trueto disable environment variable fallback.Each provider defines its own credential interface that extends
ProviderCredentialsBase. For example,SendGridCredentials,MSGraphCredentials, etc.Example