Skip to content
clearance.rest

Update the metadata of an email account

PATCH
/emails/accounts/{email}
curl --request PATCH \
  --url https://api.clearance.rest/emails/accounts/example \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "metadata": { "additionalProperty": "example" } }'

JSON Merge Patch (RFC 7396) on the account’s metadata: keys set to null are removed, arrays are replaced. Send If-Match: "<metadata_version>" to update only if nobody changed it in between; otherwise the response is 412 metadata_version_mismatch and error.details.current_version holds the current version. Limits: 16 KB, 5 levels, keys up to 64 characters.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
email
required
string
>= 3 characters

Email address (URL-encoded).

Header Parameters

Section titled “Header Parameters”
If-Match
string

Metadata version from the last read (the metadata_version field or the ETag header), for example "3". The update fails with 412 and error.details.current_version when it no longer matches; * matches any version. Without the header the update is unconditional.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

JSON Merge Patch (RFC 7396) of the metadata: keys set to null are removed, arrays are replaced.

object
metadata
required

Free-form JSON object (at most 16 KB, 5 levels deep, keys up to 64 characters).

object
key
additional properties
Examplegenerated
{
  "metadata": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
success
required
boolean
account
required

A Gmail, Outlook or Cloudflare address connected to the project.

object
id
required
string
email
required
string
email_provider
required

Provider of an email account.

string
Allowed values: gmail outlook cloudflare
status
required

CONNECTED: notifications are active. RENEWING: the subscription expired or is not set up yet and will be renewed automatically. REAUTH_REQUIRED: the last token refresh or sync failed; the owner may need to authorize again. Cloudflare addresses are always CONNECTED.

string
Allowed values: CONNECTED RENEWING REAUTH_REQUIRED
last_error
required
string | null
subscription_expires_at
required
Any of:

UTC timestamp (ISO 8601).

string
mark_as_read_authorized
required

Whether the mailbox granted the permission needed for mark_as_read.

boolean
project_id
required
string
metadata
required

Free-form JSON object (at most 16 KB, 5 levels deep, keys up to 64 characters).

object
key
additional properties
metadata_version
required

Increases on every metadata change; use it in If-Match.

integer
>= -9007199254740991 <= 9007199254740991
created_at
required

UTC timestamp (ISO 8601).

string
updated_at
required

UTC timestamp (ISO 8601).

string
Example
{
  "success": true,
  "account": {
    "email_provider": "gmail",
    "status": "CONNECTED"
  }
}

400

Section titled “400”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

401

Section titled “401”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

403

Section titled “403”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

404

Section titled “404”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

412

Section titled “412”

Default Response

Media typeapplication/json

The If-Match version does not match the current metadata version.

object
success
required
boolean
error
required
object
code
required
string
Allowed values: metadata_version_mismatch
message
required
string
details
required
object
current_version
required

The current metadata_version; read the resource again and retry.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "success": false,
  "error": {
    "code": "metadata_version_mismatch"
  }
}

413

Section titled “413”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}