Update a grant

PATCH

/v1/grants/{id}

curl --request PATCH \
  --url https://api.inboxcnx.com/v1/grants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subscribedRoles": [ "inbox" ], "subscribedLabels": [ "Label_12" ] }'

Changes a grant’s settings: moves it to another profile, pauses or resumes it, or sets the folders and labels whose mail it processes.

A profile with a higher retention than the grant’s consent covers needs consent. A lower retention, or a lower deletedRetentionDays, deletes the grant’s stored mail past it once a 7-day hold has passed; switching back within the hold deletes nothing. A paused grant skips all mail until it is unpaused. A mail is processed when it lies in one of the grant’s folders or carries one of its labels; a label covers only itself, not its sub-labels. Folders and labels together need at least one entry. A narrower filter deletes nothing: stored mail stays until the retention deletes it, and mail already delivered keeps receiving message.updated. A wider one fetches no older mail on its own; start a backfill for that. With subscribedLabels, the labels are checked against the mailbox. The response never reveals the profile to a grant token: the route needs write:connections.

Requires the write:connections scope.

Authorizations

• apiKey

Parameters

Path Parameters

id

required

string format: uuid

Request Body

Media typeapplication/json

object

profile

string

/^[a-z0-9][a-z0-9_-]{0,31}$/

consent

object

grantedAt

required

string | null format: date-time

textVersion

required

string

>= 1 characters <= 64 characters

paused

boolean

subscribedRoles

The grant’s own folders, replacing the application’s subscribedRoles. null follows the application’s again, [] subscribes no folder, so only subscribedLabels pick mail.

Array<string> | null

Allowed values: inbox sent archive drafts junk trash

subscribedLabels

Label ids of the mailbox, as GET /v1/grants/{id}/labels lists them. Replaces the grant’s labels.

Array<string>

<= 100 items

Example

{
  "subscribedRoles": [
    "inbox"
  ],
  "subscribedLabels": [
    "Label_12"
  ]
}

Responses

200

The grant’s settings

Media typeapplication/json

object

grantId

required

string

profile

required

string

paused

required

boolean

blocked

required

boolean

subscribedRoles

required

The grant’s own folders, or null when it follows the application’s.

Array<string> | null

subscribedLabels

required

Array<string>

effectiveRoles

required

The folders that apply: subscribedRoles, else the application’s.

Array<string>

Example ^generated

{
  "grantId": "example",
  "profile": "example",
  "paused": true,
  "blocked": true,
  "subscribedRoles": [
    "example"
  ],
  "subscribedLabels": [
    "example"
  ],
  "effectiveRoles": [
    "example"
  ]
}

400

Invalid body. empty_filter: no folder and no label. unknown_labels: labels lists the ids the mailbox does not have

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

The credential lacks the write:connections scope

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

No such grant or profile

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

The grant is revoked, the profile is archived, or consent is required. connection_unreadable: the mailbox cannot be asked for its labels

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}