Verify your unchecked contacts

POST/api/v1/verifications/contacts

Requires anorganization API keywith the scopeverification:write

Checks your contacts that have never been checked, newest first, up to max (at most 50,000). Contacts whose address does not exist are marked bounced and are never mailed.

Once Bounce protection is on for your account, it uses one check per address, and new contacts are checked as they arrive, so this is for contacts from before, or added while Bounce protection was off or out of checks. If you have fewer checks than it needs, nothing starts and nothing is used: a 402 whose data.quote covers it. An address Mailyte is already asking again by itself (a check that could not confirm yet) is left out, so it is never paid for twice. One such check runs at a time (a second is a 409); if the checker cannot be reached, nothing is used (a 503). The reply carries X-Mailyte-Checks-Remaining and, when it applies, X-Mailyte-Checks-Warning.

Before that, it is free and checks every never-checked contact; max is ignored.

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

maxinteger
Check at most this many contacts, newest first. Once Bounce protection is on; ignored before. Default 50,000.

Request

POST/api/v1/verifications/contacts

curl -X POST 'https://app.mailyte.com/api/v1/verifications/contacts' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "max": 2000
  }'

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

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/verifications/contacts",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "max": 2000
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/verifications/contacts', [
    'max' => 2000,
]);

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

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/verifications/contacts")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "max": 2000
}.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

Started.

dataobject
- objectstringverification
- idstring
- statusstringrunning | finished | expired | failed
  running until every address has an answer, then finished. expired: the checker could not answer some addresses within a day; they stay pending and their checks or credits were given back.
- sourcestringlist | contacts | import | campaign | automatic | single
  Where the addresses came from: - list: addresses you sent (1 check each; older runs used send credits). - contacts: your contacts that were never checked (free). - import, campaign: checks we run when you import contacts or start a campaign (free). - automatic: the day's checks of new contacts while Bounce protection is on. - single: the day's one-address checks.
- labelstring or null
- totalinteger
  Unique addresses in the run.
- countsobject
  Always sums to total.
  - validinteger
    The mailbox exists.
  - invalidinteger
    Does not exist, cannot receive mail, or is not an address. Mail to these is refused.
  - riskyinteger
    Throwaway, catch-all or role address: may not reach a person.
  - unknowninteger
    The provider would not confirm either way (Yahoo and AOL never do). Sent as normal.
  - pendinginteger
    Still being checked.
- credits_chargedinteger
  Send credits this run cost (older runs, or checks paid from credits bought or granted before launch, at 10 credits a check).
- credits_refundedinteger
  Send credits given back.
- checks_chargedinteger
  Checks drawn for this run.
- checks_refundedinteger
  Checks given back (couldn't confirm, or never answered).
- charge_unitstring or null
  checks, or null for a run paid in send credits.
- by_mailyteboolean
  True for a free check Mailyte ran on your contacts, such as the one-time check of existing contacts at launch.
- created_atstring
- finished_atstring or null

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.