API reference · Email
POST/api/email/webhooks/google

Receive Google Gmail Pub/Sub webhook

Receives Google Pub/Sub push notifications for Gmail watches. Standard session and API-key middleware are bypassed; the handler requires an Authorization: Bearer Google-signed JWT, decodes the Pub/Sub message data into a Gmail notification with emailAddress and historyId, resolves the tenant and email provider by subscription name or mailbox, validates Google configuration, and enqueues a pointer-only job into the unified inbound email queue. It does not fetch or return email content.

Request body

Content type: application/json · schema GooglePubSubPushBody

messageobjectRequired
datastringRequired
Base64-encoded Gmail notification JSON containing emailAddress and historyId.
messageIdstringRequired
Google Pub/Sub message ID.
publishTimestringRequired
ISO timestamp when Pub/Sub published the message.
subscriptionstringRequired
Full Pub/Sub subscription path, such as projects/{project}/subscriptions/{subscriptionName}.

Response body

Success response 200

anyOf (option 1)object
successbooleanRequired
Webhook was accepted.
Enum: true
queuedbooleanRequired
The notification was enqueued for asynchronous processing.
Enum: true
handoffstringRequired
Queue handoff mechanism used for the Gmail notification pointer.
Enum: unified_pointer_queue
providerIdstring <uuid>Required
Resolved email_providers.id for the Gmail mailbox.
tenantstringRequired
Tenant identifier owning the provider.
historyIdstringRequired
Gmail history ID from the decoded notification.
jobIdstring <uuid>Required
UUID assigned to the Redis queue job.
queueDepthintegerRequired
Redis queue depth after enqueue.
anyOf (option 2)object
successbooleanRequired
Webhook request was accepted but no job was enqueued.
Enum: true
messagestringRequired
Reason the webhook did not enqueue work.
Enum: No data to processNo provider foundNo google config found

Response codes

200
Webhook accepted. Either a queue job was enqueued, or the notification was safely skipped.
400
Permanent parse or validation error; Pub/Sub should not retry.
401
Bearer JWT is missing or invalid.
503
Transient enqueue or processing failure; Pub/Sub may retry.