Endpoints

Call these through the okoro proxy at https://okoro.ai/p/gmail

Action	Method	Min scope
Read profile	`GET`	`read`
List messages	`GET`	`read`
Read message	`GET`	`read`
Read attachment	`GET`	`read`
Send message	`POST`	`write`
Trash message	`POST`	`write`
Untrash message	`POST`	`write`
Modify message labels	`POST`	`write`
Batch modify messages	`POST`	`write`
Delete message	`DELETE`	`delete`
List threads	`GET`	`read`
Read thread	`GET`	`read`
Modify thread labels	`POST`	`write`
Trash thread	`POST`	`write`
Untrash thread	`POST`	`write`
List labels	`GET`	`read`
Read label	`GET`	`read`
List drafts	`GET`	`read`
Read draft	`GET`	`read`
Create draft	`POST`	`write`
Update draft	`PUT`	`write`
Send draft	`POST`	`write`
List history	`GET`	`read`

Examples

Every request requires a short-lived operation token scoped to a single action.

1. Get an operation token

Exchange your service token for a short-lived operation token scoped to a single action.

TOKEN=$(curl -sX POST "https://okoro.ai/t/tokens" \
  -H "Authorization: Bearer $OKORO_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "gmail", "scope": "read", "intent": "describe what you are doing"}' \
  | jq -r '.token')

2. Call the API

Use the operation token as a Bearer token. The proxy forwards the request to Gmail and logs the action.

Read profile

curl -X GET "https://okoro.ai/p/gmail/profile" \
  -H "Authorization: Bearer $TOKEN"

List messages

curl -X GET "https://okoro.ai/p/gmail/messages" \
  -H "Authorization: Bearer $TOKEN"

Read message

curl -X GET "https://okoro.ai/p/gmail/messages/{id}" \
  -H "Authorization: Bearer $TOKEN"

Read attachment

curl -X GET "https://okoro.ai/p/gmail/messages/{id}/attachments/{id}" \
  -H "Authorization: Bearer $TOKEN"

Send message

curl -X POST "https://okoro.ai/p/gmail/messages/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Trash message

curl -X POST "https://okoro.ai/p/gmail/messages/{id}/trash" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Untrash message

curl -X POST "https://okoro.ai/p/gmail/messages/{id}/untrash" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Modify message labels

curl -X POST "https://okoro.ai/p/gmail/messages/{id}/modify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Batch modify messages

curl -X POST "https://okoro.ai/p/gmail/messages/batchModify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete message

curl -X DELETE "https://okoro.ai/p/gmail/messages/{id}" \
  -H "Authorization: Bearer $TOKEN"

List threads

curl -X GET "https://okoro.ai/p/gmail/threads" \
  -H "Authorization: Bearer $TOKEN"

Read thread

curl -X GET "https://okoro.ai/p/gmail/threads/{id}" \
  -H "Authorization: Bearer $TOKEN"

Modify thread labels

curl -X POST "https://okoro.ai/p/gmail/threads/{id}/modify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Trash thread

curl -X POST "https://okoro.ai/p/gmail/threads/{id}/trash" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Untrash thread

curl -X POST "https://okoro.ai/p/gmail/threads/{id}/untrash" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

List labels

curl -X GET "https://okoro.ai/p/gmail/labels" \
  -H "Authorization: Bearer $TOKEN"

Read label

curl -X GET "https://okoro.ai/p/gmail/labels/{id}" \
  -H "Authorization: Bearer $TOKEN"

List drafts

curl -X GET "https://okoro.ai/p/gmail/drafts" \
  -H "Authorization: Bearer $TOKEN"

Read draft

curl -X GET "https://okoro.ai/p/gmail/drafts/{id}" \
  -H "Authorization: Bearer $TOKEN"

Create draft

curl -X POST "https://okoro.ai/p/gmail/drafts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Update draft

curl -X PUT "https://okoro.ai/p/gmail/drafts/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Send draft

curl -X POST "https://okoro.ai/p/gmail/drafts/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

List history

curl -X GET "https://okoro.ai/p/gmail/history" \
  -H "Authorization: Bearer $TOKEN"

Scopes

Your service token must be configured with at least the required scope level.

read

GET

/v1/users/*/messages /v1/users/*/messages/* /v1/users/*/messages/*/attachments/* /v1/users/*/threads /v1/users/*/threads/* /v1/users/*/labels /v1/users/*/labels/* /v1/users/*/drafts /v1/users/*/drafts/* /v1/users/*/history /v1/users/*/profile

write

GET POST PUT

/v1/users/*/messages/send /v1/users/*/drafts /v1/users/*/drafts/* /v1/users/*/drafts/send

update

GET POST PATCH

/v1/users/*/messages/*/modify /v1/users/*/messages/*/untrash /v1/users/*/messages/batchModify /v1/users/*/threads/*/modify /v1/users/*/threads/*/untrash /v1/users/*/labels/*

delete

GET POST PATCH DELETE

/v1/users/*/messages/* /v1/users/*/messages/*/trash /v1/users/*/threads/* /v1/users/*/threads/*/trash

all

GET POST PUT PATCH DELETE

/v1/**

Skill

A Claude Code skill for Gmail — token caching, scope enforcement, and audit logging built in.

gmail

View the skill, browse files, and get install instructions →