Check one address
POST
/api/v1/verifications/checkChecks 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.
Costs 10 send credits, charged only when there is an answer. A pending result costs
nothing; ask again a little later.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Send a unique value — a UUID is ideal — to make this request safe to retry. If we have already answered a request with the same key and the same body, you get that exact response back with `Idempotent-Replayed: true` and nothing is sent a second time. Reusing a key with a DIFFERENT body is a 409, because answering the first response to a second message would silently swallow it. Keys are scoped to your organization and honoured for 24 hours. A 5xx does not record a key: we cannot say whether the message left, so your retry genuinely retries. Omit the header and nothing changes. |
Request body
emailstringrequired
Request
POST
/api/v1/verifications/checkcurl -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": "<string>"
}'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": "<string>"
}),
});
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": "<string>"
},
)
data = response.json()["data"]<?php
$response = Http::withToken('mk_live_YOUR_API_KEY')
->post('https://app.mailyte.com/api/v1/verifications/check', [
'email' => '<string>',
]);
$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": "<string>"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }Response
The answer, or `pending` if it is still being checked.
dataobjectobjectstringverification_resultemailstringresultstringvalid | invalid | risky | unknown | pendingMail to `invalid` is refused. `risky` and `unknown` are sent as normal. `pending`: still being checked.
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 | could_not_confirm | checkingflagsarray<string>`role`: info@, sales@ and the like. `disposable`: a throwaway inbox (marketing to it is not sent). `catch_all`: the domain accepts any address.
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.