Wait for an email

GET

/get-email

const url = 'https://api.clearance.rest/emails/get-email?email_account=test%40domain.com&email_sender=noreply%40example.com&timestamp=1783459019000&match_regex=Verification&code_regex=%5Cd%7B6%7D';
const options = {
  method: 'GET',
  headers: {'X-Service-Timeout': '45000', 'X-API-Key': '<X-API-Key>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.clearance.rest/emails/get-email?email_account=test%40domain.com&email_sender=noreply%40example.com&timestamp=1783459019000&match_regex=Verification&code_regex=%5Cd%7B6%7D' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Service-Timeout: 45000'

Returns the newest email that matches every filter you supplied. If a matching email has already arrived, it returns immediately; otherwise the request stays open until one arrives or the timeout elapses. With no filters, the next email to arrive is returned.

Every parameter is optional. Parameters may also be sent as a JSON request body with the same field names.

match_regex and code_regex are independent: match_regex selects which emails qualify, code_regex extracts a value from the chosen email. Both are searched against the email’s text, html and subject, in that order. If code_regex has a capture group, the group is returned, otherwise the whole match. When code_regex is omitted the response has no code field; when it is given but nothing matches, code is null.

Emails delivered through a connected OAuth mailbox are visible only to the project that connected it. Emails received through Cloudflare Email Routing are visible to all projects.

Authorizations

ApiKey

Parameters

Header Parameters

X-Service-Timeout

integer

>= 1

Maximum time to wait, in milliseconds. Must be a positive integer. When the wait exceeds it, the response is HTTP 200 with error: "timeout". It can only lower the service’s own ceiling, never raise it.

Query Parameters

email_account

string format: email

Only match emails sent to this address (to).

email_sender

string format: email

Only match emails sent from this address (from).

timestamp

string

Only consider emails received after this moment. Accepts seconds, milliseconds, microseconds, or an ISO 8601 date string. Defaults to 0 (everything). When several emails match, the newest is returned.

match_regex

string

Filter. Only emails whose text, html or subject match this regular expression qualify.

code_regex

string

Extraction. Regular expression applied to the chosen email; the result goes into code.

Responses

200

The matching email, or a timeout (error: "timeout").

application/json

Any of:

object
object

object

code

Value extracted by code_regex. Only present when code_regex was sent; null when it matched nothing.

string | null

messageId

required

string | null

date

required

The email’s Date header, as an ISO 8601 string.

string | null

receivedAt

required

When the service received it, in milliseconds since the Unix epoch.

integer | null

rawSize

required

Size of the raw message in bytes.

integer | null

required

string | null

from

required

string | null

subject

required

string

text

required

string

html

required

string

headers

required

Array<object>

object

key

required

string

value

required

string

attachments

required

Array<object>

object

file_name

required

string

full_url

required

Download URL. Requires the X-API-Key header.

string format: uri

base64_data

required

The attachment contents, base64-encoded.

string

Returned with HTTP 200 when the wait exceeded X-Service-Timeout.

object

success

required

boolean

error

required

string

Allowed value: timeout

Examples

{
  "code": "123456",
  "messageId": "<CAF=abc@mail.gmail.com>",
  "date": "2026-07-11T10:00:00.000Z",
  "receivedAt": 1783459025000,
  "rawSize": 4096,
  "to": "test@domain.com",
  "from": "noreply@example.com",
  "subject": "Your verification code",
  "text": "Your code is 123456",
  "html": "<p>Your code is 123456</p>",
  "headers": [
    {
      "key": "message-id",
      "value": "<CAF=abc@mail.gmail.com>"
    }
  ],
  "attachments": [
    {
      "file_name": "invoice.pdf",
      "full_url": "https://api.clearance.rest/emails/attachments/1783459025000_1_invoice.pdf",
      "base64_data": "JVBERi0xLjQK…"
    }
  ]
}

{
  "success": false,
  "error": "timeout"
}

400

match_regex or code_regex did not compile, timestamp is not a number, or X-Service-Timeout is not a positive integer.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Examples

{
  "success": false,
  "error": "geçersiz match_regex"
}

{
  "success": false,
  "error": "geçersiz code_regex"
}

{
  "success": false,
  "error": "geçersiz timestamp"
}

{
  "success": false,
  "error": "geçersiz X-Service-Timeout"
}

401

The X-API-Key header is missing or invalid.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "geçersiz API anahtarı"
}

502

The upstream provider call failed (network error, auth error, or the provider’s own error).

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "invalid json body"
}