Create Gmail Inbox Trigger

POST

/org/:org_id/project/:project_id/trigger/gmail-inbox

POST

/api/v1/org/:org_id/project/:project_id/trigger/gmail-inbox

$ curl -X POST https://app.rightbrain.ai/api/v1/org/org_id/project/project_id/trigger/gmail-inbox \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "name": "support-inbox",
>   "target_type": "task",
>   "target_id": "0190a234-8dc6-6d08-aea9-928fcecad8f1",
>   "project_integration_id": "019dd965-fd73-8c23-57f3-a06a470a4c2b",
>   "description": "Summarises messages landing in the support label.",
>   "label_ids": [
>     "Label_12"
>   ],
>   "subject_contains": [
>     "invoice",
>     "receipt"
>   ],
>   "payload_mapping": {
>     "text": "$.message.snippet"
>   }
> }'

1 {
2   "id": "019f8a05-6f65-7001-af6f-7fa142935051",
3   "target_type": "task_agent",
4   "target_id": "019f8a05-6f65-7002-af6f-7fa142935052",
5   "name": "Support inbox intake",
6   "status": "enabled",
7   "project_integration_id": "019f8a04-5e54-7007-9f5e-6e9031824047",
8   "integration_auth_principal_id": "019f8a04-5e54-7008-9f5e-6e9031824048",
9   "email_address": "[email protected]",
10   "created": "2026-07-24T09:00:00Z",
11   "modified": "2026-07-24T09:00:00Z",
12   "created_by_user_id": "019f8a00-1a10-7003-8b1a-2a5c9d4e0003",
13   "trigger_type": "gmail_inbox",
14   "description": "Creates a support ticket task run for each new inbound email",
15   "mailbox_watch_id": "019f8a05-6f65-7003-af6f-7fa142935053",
16   "label_ids": [
17     "INBOX"
18   ],
19   "sender_filters": [
20     {
21       "type": "domain",
22       "value": "example.com"
23     }
24   ],
25   "health_state": "healthy",
26   "watch_status": "active",
27   "watch_expiration_at": "2026-07-31T09:00:00Z"
28 }

Create a Gmail inbox trigger.

project_integration_id must be an authorised Google integration in this project — authorise one first, because the trigger cannot create the grant. The filters narrow which messages fire it: label_ids, sender_filters and subject_contains are combined, so a message must satisfy all of the ones you set. label_ids and subject_contains are lists, and a message matches when any entry in the list matches.

Create a Gmail inbox trigger. `project_integration_id` must be an authorised Google integration in this project — authorise one first, because the trigger cannot create the grant. The filters narrow which messages fire it: `label_ids`, `sender_filters` and `subject_contains` are combined, so a message must satisfy all of the ones you set. `label_ids` and `subject_contains` are lists, and a message matches when any entry in the list matches.

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

org_idstringRequiredformat: "uuid"

The organization ID

project_idstringRequiredformat: "uuid"

The project ID

Request

This endpoint expects an object.

namestringRequired1-63 characters

target_typeenumRequired

Target resource type for trigger execution.

target_idstringRequiredformat: "uuid"

project_integration_idstringRequiredformat: "uuid"

descriptionstring or nullOptional<=255 characters

statusenumOptional

Lifecycle status for triggers.

label_idslist of strings or nullOptional

sender_filterslist of objects or nullOptional

subject_containslist of strings or nullOptional

payload_mappingmap from strings to any or nullOptional

task_agent_revision_idstring or nullOptionalformat: "uuid"

Response

Gmail inbox trigger created successfully

idstringformat: "uuid"

target_typeenum

Target resource type for trigger execution.

target_idstringformat: "uuid"

namestring

statusenum

Lifecycle status for triggers.

project_integration_idstringformat: "uuid"

integration_auth_principal_idstringformat: "uuid"

email_addressstring

createdstring

modifiedstring

created_by_user_idstringformat: "uuid"

task_agent_revision_idstring or nullOptionalformat: "uuid"

trigger_type"gmail_inbox"OptionalDefaults to gmail_inbox

descriptionstring or nullOptional

mailbox_watch_idstring or nullOptionalformat: "uuid"

label_idslist of strings or nullOptional

sender_filterslist of objects or nullOptional

subject_containslist of strings or nullOptional

payload_mappingmap from strings to any or nullOptional

health_stateenumOptionalDefaults to healthy

health_reasonstring or nullOptional

watch_statusenum or nullOptional

Lifecycle/health status for Gmail mailbox watches.

watch_expiration_atstring or nullOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

503

Service Unavailable Error