Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getinboxzero.com/llms.txt

Use this file to discover all available pages before exploring further.

Automated Setup: If you ran inbox-zero setup-google, the Pub/Sub topic and subscription were created automatically. Skip to the “For local development” section below.
Complete Google OAuth first. PubSub enables real-time email notifications so Inbox Zero is notified immediately when new emails arrive.

​
1. Create a topic

  1. Go to the Pub/Sub Topics page in Google Cloud Console.
  2. Click Create Topic.
  3. Enter a topic ID (e.g., inbox-zero-emails).
  4. Click Create.

​
2. Grant Gmail publish access

Gmail needs permission to send notifications to your topic. This is the step that allows Google’s servers to push email events into your Pub/Sub topic.
  1. Click your topic name to open it.
  2. Go to the Permissions tab (you may see it labeled “Info Panel” on the right side — look for the “Permissions” section).
  3. Click Add Principal.
  4. In the “New principals” field, enter: gmail-api-push@system.gserviceaccount.com
  5. In the “Role” dropdown, select Pub/Sub Publisher.
  6. Click Save.
gmail-api-push@system.gserviceaccount.com is Google’s service account that sends Gmail push notifications. This is not your account — it’s a Google-managed service account used by the Gmail API. See the official docs for more details.

​
3. Create a push subscription

  1. In your topic, go to the Subscriptions tab.
  2. Click Create Subscription.
  3. Set the Delivery type to Push.
  4. Set the Endpoint URL to: https://yourdomain.com/api/google/webhook?token=TOKEN
  5. Click Create.

​
4. Update your environment variables

Set these in your .env file:
  • GOOGLE_PUBSUB_TOPIC_NAME — the full topic name (e.g., projects/your-project-id/topics/inbox-zero-emails)
  • GOOGLE_PUBSUB_VERIFICATION_TOKEN — the value of TOKEN you used in the webhook URL above
If your deployment protects /api/google/webhook with upstream authentication, you can set GOOGLE_PUBSUB_VERIFICATION_TOKEN to an empty string to intentionally disable query-parameter verification. Leaving it unset is treated as a misconfiguration.

​
For local development

Use ngrok to expose your local server: 
ngrok http 3000
Then update the webhook endpoint in the Google PubSub subscriptions dashboard to use your ngrok URL (e.g., https://abc123.ngrok.io/api/google/webhook?token=TOKEN).