Google Mail Real Time Events

🚧

If you are using real-time events for the EMAIL category for the first time, ensure that a webhookUrl is registered. You can do this using the Register Webhook for a Category API.

List of Events Supported by Google Mail

Subscribe to Google Mail Real Time Events

1. Complete Pre-requisites

   Before hitting the subscribe endpoint, ensure you have completed the first three steps of the Google Mail Pub/Sub Setup Guide.

2. Configure the Topic Name

   The metadata.topicName parameter is required. You must provide the full resource path rather than just the display name.
   1. Correct Format: projects/{project-id}/topics/{topic-name}
   2. Example: projects/my-project-identifier/topics/my-topic-name

3. Locate Your Topic

   If you aren't sure what your topic path is, you can find it in the Google Cloud Console Topics List under Pub/Sub > Topics.

Subscribe to All Mail Folders

By default, the subscription applies to all folders in the mailbox (Inbox, Sent Items, Drafts, etc.).

Note: We recommend subscribing only to specific folders of interest. This reduces unnecessary event volume, particularly because Google triggers multiple new/delete events while a user is drafting an email.

Example request:

curl --location 'https://api.getknit.dev/v1.0/events.subscribe' \
--header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "events": [
        "email_messages_new",
        "email_messages_modified",
        "email_messages_deleted"
    ],
    "metadata": {
        "topicName": "projects/my-project-identifier/topics/my-topic-name"
    }
}'

Subscribe to Specific Folder(s)

If you want to receive events only for specific mail folders, you can provide a list of folderIds in the metadata object.

You can retrieve folder IDs using the List Folders API.

Example request (subscribing to specific folders):

curl --location 'https://api.getknit.dev/v1.0/events.subscribe' \
--header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "events": [
        "email_messages_new",
        "email_messages_modified",
        "email_messages_deleted"
    ],
    "metadata": {
        "topicName": "projects/my-project-identifier/topics/my-topic-name",
        "folderIds": [
            "INBOX",
            "SENT"
        ]
    }
}'

Important Notes

1. Calling the Subscribe to Real Time Events API multiple times overwrites the existing subscription.
2. The latest request fully replaces any previously subscribed events or metadata (including folder filters).