Wait for an email (verification inbox)

GET/api/v2/agent-mailboxes/:id/wait-for-email

Holds the request open until a matching email arrives or the timeout passes (1 to 60 seconds).

Needs an API key with the read scope. Scopes

Parameters

Path

idstringrequired

The agent mailbox id, or me.

Query

tostring

Only mail sent to this address.

fromstring

Only mail from this address or domain.

subjectstring

Only mail whose subject contains this text.

timeoutnumberdefault 30

Seconds to wait, 1 to 60.

sincestring

Only mail received after this RFC 3339 time.

Notes

Returns the message and any one-time code (otp_code) or sign-in link (magic_link) found in it.
Use it right after triggering a sign-up or login that emails a code.
Without since it looks at the last minute.
A message the injection shield rates high risk comes back withheld, with no code.
With from, the sign-in link is returned only if it points at that sender's own domain.
At most a few waits can be open per mailbox, key and workspace (429 when exceeded).
When nothing arrives you get 200 with found: false.

curl -X GET "https://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY"

const res = await fetch("https://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
  },
});

console.log(res.status, await res.json());

import os, requests

res = requests.get(
    "https://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
    },
)
print(res.status_code, res.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOLTRIX_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

<?php

$ch = curl_init("https://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("KOLTRIX_API_KEY"),
    ],
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $response;

Success.

{
  "found": true,
  "message": {
    "id": "7e6d5c4b-3a29-4f18-8e7d-6c5b4a392817",
    "subject": "<<<UNTRUSTED_EMAIL_CONTENT id=… Your code … UNTRUSTED_EMAIL_CONTENT>>>",
    "injection_risk": "none",
    "withheld": false
  },
  "otp_code": "482913",
  "magic_link": "https://app.example.com/auth/verify?t=abc123",
  "links": [
    "https://app.example.com/auth/verify?t=abc123"
  ]
}

The API key is missing, malformed, unknown or revoked.

{
  "error": "invalid or revoked api key"
}

The key is valid but does not have the read scope.

{
  "error": "missing permission: read"
}

No such record in this workspace.

{
  "error": "agent mailbox not found"
}

More than 60 requests a minute on this key. Wait Retry-After seconds. No code field.

Retry-After: 60

{
  "error": "rate limit exceeded — 60 requests per minute per API key"
}

Try it below with your own key. Every sample reads the key from KOLTRIX_API_KEY.

Try it

Send this request from your browser.

Input

What you send

API key

Stays in this browser tab (sessionStorage) and goes only to api.koltrix.com. Create one under Settings → API keys.

Requests are real. Koltrix has no test mode, so use a dedicated key with only the permissions you need and revoke it when you are done.

idstringrequired

tostring

fromstring

subjectstring

timeoutnumber

sincestring

GEThttps://api.koltrix.com/api/v2/agent-mailboxes/me/wait-for-email

Output

What comes back

The response appears here.
Press Send request.