Check an email

GET

/v1/addresses/{address}/checks

curl --request GET \
  --url 'https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev/checks?expect_host=staging.example.com&expect_text=Welcome%2C%20Maya&expect_language=de&type=code' \
  --header 'Authorization: Bearer <token>' \
  --header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code'

Runs checks on one email the address received: the one named by email_id, or the newest matching the filters. Doesn’t wait: wait for the email first (/code, /link or /count). Each check passes, fails, warns or is skipped, with a one-line reason: SPF, DKIM and DMARC (the receiving server’s verdicts), links to localhost or a private address (also after a redirect), plain http links, the site its sign-in, verify, reset or invite link goes to (expect_host), whether it says when its code or link expires, a plain-text version, the HTML’s size against Gmail’s 102 KB limit, image-only emails, whether it fits a phone, and, when asked, given phrases (expect_text) and the language (expect_language). Verdicts only: never the email’s text or its links (reasons name at most a domain or a link’s host).

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

email_id

string format: uuid

The email to check, as /count gives it. Default: the newest that matches.

since

string format: date-time

Only email received at or after this time.

expect_host

string

The site its sign-in, verify, reset or invite link should go to, after any redirect (subdomains count). Without it, that check is skipped.

Example

staging.example.com

expect_text

Array<string>

<= 10 items

A phrase the subject or body should contain; repeat for more (up to 10). Case, curly quotes and spacing don’t matter, and the answer names only the missing ones.

Example

?expect_text=Welcome%2C%20Maya

expect_language

string

The language it should be in, such as de or pt-BR. Without it, that check is skipped.

Example

de

service

string

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

type

string

Allowed values: code link

Only emails with a code, or with a link. Codes leave out coupons, and links count verify, magic_signin, invite and reset, unless subtype says otherwise.

subtype

string

With type, comma-separated: otp or coupon for codes; verify, magic_signin, invite, reset or other for links; or any.

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

Responses

200

The checks

Media typeapplication/json

object

address

string

email

Which email was checked, without its content.

object

id

string format: uuid

received_at

string format: date-time

service

string | null

service_domain

string | null

type

Its main code or link.

string | null

Allowed values: code link

subtype

string | null

passed

No check failed. Warnings don’t count.

boolean

failed

Array<string>

warnings

Array<string>

checks

Array<object>

object

check

string

Allowed values: spf dkim dmarc local_links plain_http expected_host expiry plain_text size images_only layout expected_text language

status

string

Allowed values: pass fail warn skip

detail

string

Example

{
  "email": {
    "type": "code"
  },
  "checks": [
    {
      "check": "spf",
      "status": "pass",
      "detail": "The sending server is allowed to send for acme.example."
    }
  ]
}

400

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}

404

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}