Skip to content
clearance.rest

List email accounts

GET
/emails/accounts
curl --request GET \
  --url 'https://api.clearance.rest/emails/accounts?limit=50' \
  --header 'X-API-Key: <X-API-Key>'

The project’s Gmail, Outlook and Cloudflare addresses, newest first. Filter by status, provider, address and metadata. The status filter is applied after loading, so a page can contain fewer than limit items; a non-null next_cursor means the list continues. Filter on metadata values with metadata.<key>=<string> query parameters (top-level keys of letters, digits, _ and -, up to 64 characters; the value is compared as a string; several filters must all match), and on missing keys with metadata_absent=<key>,<key> (comma-separated).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
status
Array<string>
Allowed values: CONNECTED RENEWING REAUTH_REQUIRED

Comma-separated connection statuses; an account matches when it has any of them (default: all).

email_provider
Array<string>
Allowed values: gmail outlook cloudflare

Comma-separated providers; an account matches when it has any of them (default: all).

email
string

Exact match (case-insensitive).

limit
integer
default: 50 >= 1 <= 200

Page size (1-200).

cursor
string

The next_cursor value of the previous page.

metadata_absent
string

Comma-separated metadata keys; the account must have none of them.

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
success
required
boolean
accounts
required
Array<object>

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
next_cursor
required
Any of:

Opaque cursor of the next page.

string
Example
{
  "success": true,
  "accounts": [
    {
      "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
}