> ## 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.

# Google PubSub

> Configure Gmail push notifications with Google PubSub

<Tip>
  **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.
</Tip>

Complete [Google OAuth](/hosting/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](https://console.cloud.google.com/cloudpubsub/topic/list) 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**.

<Info>
  `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](https://developers.google.com/gmail/api/guides/push#grant_publish_rights_on_your_topic) for more details.
</Info>

### 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:

```bash theme={null}
ngrok http 3000
```

Then update the webhook endpoint in the [Google PubSub subscriptions dashboard](https://console.cloud.google.com/cloudpubsub/subscription/list) to use your ngrok URL (e.g., `https://abc123.ngrok.io/api/google/webhook?token=TOKEN`).