Create a batch of email address lookups

POST

/v1/lookup/email/batch

const answer = await bird.lookup.emailBatch({
  emails: ["aisha.khan@example.com", "not-an-email"],
});
for (const item of answer.data) console.log(item.email, item.result);

answer = client.lookup.email_batch(emails=["aisha.khan@example.com", "not-an-email"])
for item in answer.data:
    print(item.email, item.result)

answer, err := client.Lookup.EmailBatch(context.Background(), bird.LookupEmailBatchParams{
	Emails: []string{"aisha.khan@example.com", "not-an-email"},
})
if err != nil {
	log.Fatal(err)
}
for _, item := range *answer.Data {
	fmt.Println(*item.Email, *item.Result)
}

$answer = $bird->lookup->emailBatch(
    (new EmailLookupBatchRequest())->setEmails(['aisha.khan@example.com', 'not-an-email']),
);
foreach ($answer->getData() ?? [] as $item) {
    echo $item->getEmail(), ' ', $item->getResult();
}

bird lookup email-batch \
  --emails aisha.khan@example.com \
  --emails not-an-email

curl -X POST "https://us1.platform.bird.com/v1/lookup/email/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "aisha.khan@example.com",
      "not-an-email"
    ]
  }'

Odpowiedź200

{
  "data": [
    {
      "email": "aisha.khan@example.com",
      "valid": true,
      "result": "risky",
      "delivery_confidence": 42,
      "flags": [
        "role",
        "free_provider"
      ]
    }
  ]
}

Assesses up to 1,000 email addresses synchronously and returns one result per input in submission order. Malformed addresses receive individual assessments. Duplicate addresses remain separate entries and each answered entry is billed at the email lookup rate. Use Create an email address lookup for a single address. A batch consumes one request allowance under the shared lookup rate limit, regardless of its number of addresses.

Requests must fit within 128 KiB. Split larger lists into separate requests. Reuse an Idempotency-Key for retries of the same batch. Successful responses up to 256 KiB can be retained for replay; larger responses are returned but are not retained, so retrying can perform and charge for another batch. An unavailable lookup returns 503 without charging for the batch.

Treść żądania

emails

array of string

wymagane

Addresses to assess in submission order. Surrounding whitespace is trimmed and case is preserved. Malformed addresses receive individual assessments. Duplicates are assessed and billed at each position. The request must also fit within the 128 KiB request-body limit.

Treść odpowiedzi

data

array of object

wymagane

One assessment per submitted address, in submission order, including duplicates.

Pokaż atrybuty podrzędne

data.email

string

wymagane

The submitted value after trimming surrounding whitespace. May be empty or malformed.

data.valid

boolean

wymagane

The provider's validity assessment for the address. Read it with result and delivery_confidence when deciding whether to send; it does not guarantee delivery.

data.result

string

wymagane

data.delivery_confidence

integer

wymagane

How likely mail to this address is to be delivered, from 0 (certain not to be) to 100 (certain to be). Read it alongside result rather than instead of it, because the same score can sit under neutral or risky for different reasons.

data.flags

array of string

wymagane

Notable characteristics of the address. Empty when none apply.

data.reason

string

An explanation for the assessment. Can accompany an undeliverable, risky, or typo result; omitted when no recognized reason is available.

data.did_you_mean

string

The address this one looks like a misspelling of. Absent unless a correction was found, which in practice means result is typo. Offer it to whoever typed the original rather than sending to it unasked, because it is a guess and the address they meant may be neither one.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy

const answer = await bird.lookup.emailBatch({
  emails: ["aisha.khan@example.com", "not-an-email"],
});
for (const item of answer.data) console.log(item.email, item.result);

answer = client.lookup.email_batch(emails=["aisha.khan@example.com", "not-an-email"])
for item in answer.data:
    print(item.email, item.result)

answer, err := client.Lookup.EmailBatch(context.Background(), bird.LookupEmailBatchParams{
	Emails: []string{"aisha.khan@example.com", "not-an-email"},
})
if err != nil {
	log.Fatal(err)
}
for _, item := range *answer.Data {
	fmt.Println(*item.Email, *item.Result)
}

$answer = $bird->lookup->emailBatch(
    (new EmailLookupBatchRequest())->setEmails(['aisha.khan@example.com', 'not-an-email']),
);
foreach ($answer->getData() ?? [] as $item) {
    echo $item->getEmail(), ' ', $item->getResult();
}

bird lookup email-batch \
  --emails aisha.khan@example.com \
  --emails not-an-email

curl -X POST "https://us1.platform.bird.com/v1/lookup/email/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "aisha.khan@example.com",
      "not-an-email"
    ]
  }'

Odpowiedź200

{
  "data": [
    {
      "email": "aisha.khan@example.com",
      "valid": true,
      "result": "risky",
      "delivery_confidence": 42,
      "flags": [
        "role",
        "free_provider"
      ]
    }
  ]
}