Skip to content
clearance.rest

Wait for an email

GET
/emails/wait
curl --request GET \
  --url https://api.clearance.rest/emails/wait \
  --header 'X-API-Key: <X-API-Key>'

Returns the newest email that matches the filters. If a matching email already arrived the response is immediate; otherwise the request stays open until one arrives, the X-Service-Timeout (ms, at most 5 minutes) elapses (HTTP 200 with success: false and error.code: wait_timeout) or the client disconnects. Every delivered email is charged once.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
email_account
string
>= 1 characters

Only emails sent to this address.

email_sender
string
>= 1 characters

Only emails from this address.

timestamp
number

Only emails received at or after this time (seconds, milliseconds or microseconds since the epoch).

match_regex
string
<= 2000 characters

Filter: only emails whose text, html or subject matches.

code_regex
string
<= 2000 characters

Extracts a value (first capture group, else the whole match) into code.

mark_as_read
boolean

Mark the email as read after the response (requires the project setting and the mailbox permission). The response tells whether it was scheduled.

Header Parameters

Section titled “Header Parameters”
X-Service-Timeout
integer
>= 1

Maximum time to wait in milliseconds (positive integer). Without it the request waits at most 5 minutes; a larger value is capped at 5 minutes.

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
Any of:
object
success
required
boolean
id
required
string
code

Present only when code_regex was given; null when nothing matched.

string | null
message_id
required
string | null
date
required
Any of:

UTC timestamp (ISO 8601).

string
received_at
required

UTC timestamp (ISO 8601).

string
raw_size
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
to
required
string | null
from
required
string
subject
required
string
text
required
string
html
required
string
headers
required
Array<object>
object
key
required
string
value
required
string
attachments
required
Array<object>

An attachment of a delivered email; download it with emails.getAttachment.

object
key
required
string
file_name
required
string
content_type
required
string
size
required
integer
>= -9007199254740991 <= 9007199254740991
url
required

Download URL (requires the API key).

string
mark_as_read

Present only when mark_as_read=true was requested.

string
Allowed values: scheduled disabled not_authorized unsupported
price
required

Amount charged for this delivery (USD); 0 when the email was already charged.

number
balance
required

Available team balance after the delivery (USD).

number
Example
{
  "success": true,
  "mark_as_read": "scheduled"
}

400

Section titled “400”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: validation_error invalid_service_timeout invalid_regex invalid_timestamp
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "validation_error"
  }
}

401

Section titled “401”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: missing_api_key invalid_api_key
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "missing_api_key"
  }
}

402

Section titled “402”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: insufficient_balance spend_limit_exceeded
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "insufficient_balance"
  }
}

403

Section titled “403”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: team_suspended email_not_verified invalid_mcp_token
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "team_suspended"
  }
}