Wait for a verification, sign-in, invite or reset link

GET

/v1/addresses/{address}/link

const url = 'https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev/link?timeout=30&unused=false';
const options = {
  method: 'GET',
  headers: {
    'Proxy-Mail-QA-Test': 'sign-up%20%E2%80%BA%20sends%20one%20code',
    'Proxy-Mail-QA-Run-Retry': 'true',
    Authorization: 'Bearer <token>'
  }
};

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.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev/link?timeout=30&unused=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Proxy-Mail-QA-Run-Retry: true' \
  --header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code'

Returns the newest such link received since since, waiting up to timeout seconds. We never open links: whoever calls decides whether to.

Authorizations

apiKey

Parameters

Path Parameters

address

required

string format: email

The test address, URL-encoded. A variant also works: capitals, or a +tag (k7f2x9ab12cd+o’brien@mailclub.dev). It acts on the plain address; waiting on a +tag variant, or listing its messages, only finds mail sent to that variant.

Example

k7f2x9ab12cd@mailclub.dev

Query Parameters

timeout

integer

default: 30 <= 30

Seconds to wait for a match. 0 checks once.

service

string

Only match email from this service, by name or domain (e.g. ‘spotify’).

since

string format: date-time

Only match email received at or after this time. Default: 15 minutes before the request.

unused

boolean

True: only a code or link nobody has used yet. One counts as used once it’s returned by a wait, or opened or copied in the app.

type

string

Comma-separated: verify, magic_signin, invite, reset, or any (also other links). Default: the first four.

app

boolean

True: only links that open an app (myapp://verify?…, Expo’s exp://…), for mobile tests. false: only web links. Left out: either; when an email has both for the same thing, the web link comes first.

Header Parameters

Proxy-Mail-QA-Run

string format: uuid

A run’s id (POST /v1/runs): adds what this call saw to the run. If it can’t be added (the run finished, or isn’t in this project), the call still works and the Proxy-Mail-QA-Run-Warning response header says why.

Proxy-Mail-QA-Test

string

<= 600 characters

With Proxy-Mail-QA-Run: the test this call belongs to, percent-encoded (encodeURIComponent), up to 200 characters once decoded. The run’s report shows it beside what the call saw.

Example

sign-up%20%E2%80%BA%20sends%20one%20code

Proxy-Mail-QA-Run-Retry

string

Allowed values: true

True when you’ll call again if nothing arrives (waits longer than 30 seconds), so only the last call’s “nothing arrived” is added to the run.

Responses

200

The link

application/json

A code or link and nothing else from the email.

object

address

string

type

string

Allowed values: code link

subtype

Otp or coupon; verify, magic_signin, invite, reset or other.

string

value

The code, or the link URL.

string

service

Who sent it, e.g. Spotify.

string | null

service_domain

string | null

received_at

string format: date-time

expires_at

Only when the email says how long it lasts.

string | null format: date-time

email_id

string format: uuid

Example

{
  "type": "code"
}

404

Nothing arrived in time, or the address isn’t in this project. hint says why as far as we can tell; after a wait, refused lists mail we turned away since since.

application/json

object

error

string

message

string

hint

What we refused, or the likeliest cause, such as an email provider in sandbox mode.

string

refused

Mail we refused for the address, newest first. Refusals for the same reason within an hour share one entry with a count.

Array<object>

object

reason

string

Allowed values: too_large address_limit daily_limit

first_at

string format: date-time

last_at

string format: date-time

count

integer

size_bytes

The largest refused message, in bytes.

integer | null

help

string format: uri

Example

{
  "error": "not_found",
  "refused": [
    {
      "reason": "too_large"
    }
  ],
  "help": "https://proxymail.qa/troubleshooting"
}