Waiting for an email

GET /emails/wait keeps the request open until a matching email arrives in one of your project’s mailboxes, then answers with it. An email that already arrived is returned immediately.

Request

Parameter
email_account	Only emails sent to this address of yours.
email_sender	Only emails from this sender.
timestamp	Only emails received after this time, in seconds, milliseconds or microseconds since the epoch. Default: everything.
match_regex	Only emails where the text, the HTML or the subject matches (at most 2000 characters).
code_regex	Extracts a code: the first capture group, otherwise the whole match.
mark_as_read	true marks the email as read in the mailbox after the response. Default false. See below.
X-Service-Timeout	Header. The longest wait in milliseconds; at most 5 minutes. See Waiting for results.

curl

curl -G https://api.clearance.rest/emails/wait \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "X-Service-Timeout: 120000" \
  --data-urlencode "email_account=me@example.com" \
  --data-urlencode "email_sender=noreply@example.org" \
  --data-urlencode "code_regex=(\d{6})"

Node.js

const email = await client.emails.wait(
  { emailAccount: 'me@example.com', emailSender: 'noreply@example.org', codeRegex: '(\\d{6})', markAsRead: true },
  { timeout: 120_000 },
);
console.log(email.code, email.subject);

PHP

$email = $client->emails->wait(
    emailAccount: 'me@example.com',
    emailSender: 'noreply@example.org',
    codeRegex: '(\d{6})',
    markAsRead: true,
    timeout: 120_000,
);
echo $email['code'], ' ', $email['subject'];

Response

{
  "success": true,
  "id": "0190...",
  "code": "123456",
  "message_id": "<...>",
  "date": "2026-10-25T10:00:00.000Z",
  "received_at": "2026-10-25T10:00:03.120Z",
  "raw_size": 4096,
  "to": "me@example.com",
  "from": "noreply@example.org",
  "subject": "Your code",
  "text": "...",
  "html": "...",
  "headers": [{ "key": "message-id", "value": "<...>" }],
  "attachments": [
    {
      "key": "0190..._1_invoice.pdf",
      "file_name": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 2048,
      "url": "https://api.clearance.rest/emails/attachments/0190..._1_invoice.pdf"
    }
  ],
  "mark_as_read": "scheduled",
  "price": 0.002,
  "balance": 9.998
}

code is present only when you sent a code_regex; it is null when the expression matched nothing.

Attachments

Download an attachment with its url, or GET /emails/attachments/{key}, using your API key. The response is the raw file. Another project’s attachment, or an unknown key, is 404 attachment_not_found.

Marking emails as read

Pass mark_as_read=true and the email is marked as read in the mailbox after the response is sent, so your automation can use the mailbox’s unread count as its own queue. The response says what will happen:

mark_as_read	Meaning
scheduled	The email will be marked as read.
disabled	The project has not enabled marking as read.
not_authorized	This mailbox was connected without the permission to modify mail.
unsupported	The address is an address we host; there is nothing to mark.

Marking as read needs two things:

1. Enable it for the project. In the console, open the project’s Settings and turn on Allow marking emails as read.
2. Connect mailboxes with the wider permission. With the setting on, new Gmail and Outlook connections ask for permission to modify mail; with it off they ask only to read. A mailbox connected earlier keeps its original permission and answers not_authorized until it is connected again.

Billing

An email is charged when it is delivered to you, just before the response is returned. The same email is not charged again if you receive it twice. If the balance or a spend limit cannot cover it, the request fails with 402 and the email is left unconsumed. See Billing.

When nothing arrives

After the wait time the response is 200 with success: false and error.code wait_timeout. The SDKs throw WaitTimeoutError. Other failures: 400 invalid_regex, 400 invalid_timestamp, 400 invalid_service_timeout.

Without waiting

Subscribe to the opt-in email.received event to be called whenever an email arrives.