Waiting for an email

GET /emails/get-email returns the email that matches your filters, waiting for it if it has not arrived yet.

It does not matter how the email reaches us. The recipient can be an address on a domain routed through clearance.rest, or a Gmail or Outlook mailbox you have connected. Your code is the same either way.

curl

curl -G https://api.clearance.rest/emails/get-email \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "X-Service-Timeout: 60000" \
  --data-urlencode "email_account=test@domain.com" \
  --data-urlencode "match_regex=Verification" \
  --data-urlencode "code_regex=\d{6}"

Node.js

const email = await clearanceRest.emails.wait({
  emailAccount: 'test@domain.com',
  matchRegex: 'Verification',
  codeRegex: '\\d{6}',
  timeout: 60000,
});
console.log(email.code, email.subject);

PHP

$email = $client->emails->wait(
    emailAccount: 'test@domain.com',
    matchRegex: 'Verification',
    codeRegex: '\d{6}',
    timeout: 60_000,
);
echo $email['code'];

{
  "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": []
}

Filters

Every parameter is optional. With none, the next email to arrive is returned.

Parameter	Effect
email_account	Only emails sent to this address.
email_sender	Only emails sent from this address.
timestamp	Only emails received after this moment. Seconds, milliseconds, microseconds or an ISO 8601 string.
match_regex	Filter. Only emails whose text, html or subject match qualify.
code_regex	Extraction. Applied to the chosen email; the result goes into code.

When several emails match, the newest is returned, and an email that arrived before your request counts. Pass a timestamp taken before you trigger the email so an old message cannot satisfy a new wait.

match_regex and code_regex are independent: one selects the email, the other pulls a value out of it. Both are searched in the email’s text, then html, then subject. If code_regex has a capture group, the group is returned, otherwise the whole match. Omit code_regex and the response has no code field at all; give it and nothing matches, and code is null.

You can also send the parameters as a JSON request body with the same names.

Which emails you can see

• Emails delivered to a connected Gmail or Outlook mailbox are visible only to the project that connected it.
• Emails received on a routed domain are visible to every project. Give each project distinct addresses, or filter with email_account.

Attachments

Each attachment has a file_name, the file as base64_data, and a full_url to download it. The URL needs your API key, so send the X-API-Key header, or add ?api_key= if the client cannot set headers.

curl -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  https://api.clearance.rest/emails/attachments/1783459025000_1_invoice.pdf \
  -o invoice.pdf

Timeout

The wait lasts at most 5 minutes; lower it with X-Service-Timeout. When it runs out the response is HTTP 200 with { "success": false, "error": "timeout" }. See Timeouts.