Check one address

POST/api/v1/verifications/check

Requires anorganization API keywith the scopeverification:write

Checks one address and answers in the same call when it can — a mailbox we have not seen before can take a few seconds. Use it at sign-up, before an address goes into your database.

Uses one check, and only when there is an answer: a pending result, "couldn't confirm" and "not an email address" cost nothing; for pending, ask again a little later. The answer says which in checks_used (1 when it used a check, 0 when it was free), and the reply carries X-Mailyte-Checks-Remaining. With no checks left it is a 402 naming the pack that covers it.

Before checks launch on your account, an answer costs 10 send credits (or one of the list checks your plan includes this month) instead, charged only when there is an answer.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string	Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.

Request body

emailstringrequired
The address to check.

Request

POST/api/v1/verifications/check

curl -X POST 'https://app.mailyte.com/api/v1/verifications/check' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com"
  }'

const response = await fetch('https://app.mailyte.com/api/v1/verifications/check', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "ada@example.com"
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/verifications/check",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "email": "ada@example.com"
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/verifications/check', [
    'email' => 'ada@example.com',
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/verifications/check")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "email": "ada@example.com"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

The key names its own organization, so no X-Organization-ID header is needed.

Response

The answer, or `pending` if it is still being checked.

dataobject
- objectstringverification_result
- emailstring
- resultstringvalid | invalid | risky | unknown | pending
  The answer. Mail to invalid is refused; risky and unknown are sent as normal; pending is still being checked. risky with reason inbox_full means the mailbox has no space: while Bounce protection is on, marketing to this contact waits 7 days and the address is checked again.
- reasonstringmailbox_exists | mailbox_does_not_exist | domain_cannot_receive_mail | misspelt_domain | invalid_syntax | disposable_address | accepts_all_addresses | role_address | provider_does_not_confirm | inbox_full | could_not_confirm | checking
- flagsarray<string>
  role: info@, sales@ and the like. disposable: a throwaway inbox (marketing to it is not sent). catch_all: the domain accepts any address. full: the mailbox has no space.
- suggestionstring or null
  For misspelt_domain only: the address as it was probably meant (ada@gmail.con gives ada@gmail.com). Null for every other answer.
- checks_usedinteger0 | 1
  Present while checks are on: 1 when this answer used a check, 0 when it was free (couldn't confirm, not an email address, or still being checked).

Returned inside the standard envelope.

Errors

Status	When
`401`	The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
`403`	The 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.
`404`	No such resource in this organization.
`422`	The request was understood but the values were not acceptable.
`429`	Too 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.