Count how many addresses look bad (free)

POST/api/v1/verifications/peek
Requires anorganization API keywith the scopeverification:read

About how many of these addresses look bad — invalid, throwaway, or a full inbox we already know of — free, and never which ones. Nothing is probed: the count comes from what we already know and from checks that need no conversation with a mail server.

The answer is deliberately rough, so a free count never becomes a free answer:

band When Numbers
too_few fewer than 10 distinct addresses none; we do not look
fewer_than_10 fewer than 10 look bad none
about 10 or more look bad look_bad_about: rounded down to tens, or to two significant figures from 1,000 (12,873 → 12,000); look_bad_percent_about, rounded down

partial: true means the checker could not be asked, so the count covers only broken addresses, misspelt domains and domains that cannot receive mail.

Addresses are counted once, whatever their letter case. Up to 50,000 a request; more is a 422. Free, but limited to 30 counts an hour and 100 a UTC day per account (then 429 with Retry-After); the same set again within 10 minutes is answered from memory and does not count.

Request body

  • addressesarray<string>required

    The addresses to count. `emails` is accepted as another name for it.

Request

POST/api/v1/verifications/peek
curl -X POST 'https://app.mailyte.com/api/v1/verifications/peek' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": [
      "ada@example.com",
      "grace@example.org",
      "…"
    ]
  }'
The key names its own organization, so no X-Organization-ID header is needed.

Response

The count. Every accepted request answers 200, fewer than 10 addresses included.

  • dataobject
    • objectstringaddress_count
    • totalinteger

      Distinct addresses counted.

    • bandstringtoo_few | fewer_than_10 | about

      `too_few`: fewer than 10 addresses, so we did not look. `fewer_than_10`: fewer than 10 look bad. `about`: 10 or more look bad, and the numbers say about how many.

    • look_bad_aboutinteger

      About how many look bad, rounded down (to tens; to two significant figures from 1,000). Null unless `band` is `about`.

    • look_bad_percent_aboutinteger

      The same as a whole percentage of `total`, rounded down. Null unless `band` is `about`.

    • partialboolean

      True when the checker could not be asked: only broken addresses, misspelt domains and domains that cannot receive mail were counted.

Returned inside the standard envelope.

Errors

StatusWhen
401The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
403The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
404No such resource in this organization.
422The request was understood but the values were not acceptable.
429Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.