Een e-mailadres opzoeken
Eén aanroep vertelt je of een adres mail accepteert. Gebruik het bij registratie, of voordat je op een lead reageert, om adressen die zouden bouncen buiten je verzendlijst te houden. Alles hier vereist een API-sleutel met het lookup-bereik.
Een adres opzoeken
const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
// result is an open vocabulary; delivery_confidence is always comparable.
console.log(answer.result, answer.delivery_confidence);answer = client.lookup.email(email="aisha.khan@example.com")
# result is an open vocabulary; delivery_confidence is always comparable.
print(answer.result, answer.delivery_confidence)answer, err := client.Lookup.Email(context.Background(), bird.LookupEmailParams{
Email: "aisha.khan@example.com",
})
if err != nil {
log.Fatal(err)
}
// result is an open vocabulary; delivery_confidence is always comparable.
fmt.Println(*answer.Result, *answer.DeliveryConfidence)$answer = $bird->lookup->email(
(new EmailLookupRequest())->setEmail('aisha.khan@example.com'),
);
// result is an open vocabulary; delivery_confidence is always comparable.
echo $answer->getResult(), ' ', $answer->getDeliveryConfidence();bird lookup email --email aisha.khan@example.comcurl -X POST "https://us1.platform.bird.com/v1/lookup/email" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "aisha.khan@example.com"
}'Een batch opzoeken
Gebruik POST /v1/lookup/email/batch om tot 1.000 adressen in één verzoek te beoordelen:
Codevoorbeeld
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"]}'De data-array in het antwoord bevat één beoordeling per invoer, in volgorde van inzending. Misvormde adressen krijgen individuele beoordelingen. Dubbele adressen blijven afzonderlijke vermeldingen en elke beantwoorde vermelding wordt gefactureerd. Omringende witruimte wordt verwijderd en hoofdlettergebruik blijft behouden.
Houd elk verzoek binnen 128 KiB. Splits grotere lijsten in afzonderlijke batches. Als je kiest voor idempotent opnieuw proberen, gebruik dan een unieke sleutel per batch. Antwoorden tot 256 KiB kunnen worden bewaard voor replay; grotere antwoorden worden zonder replaybeveiliging geretourneerd, dus opnieuw proberen kan een nieuwe batch uitvoeren en in rekening brengen. Zie de batch-API-referentie.
Hoe je het adres schrijft
Stuur een kaal adres, precies zoals je het hebt. Een opzoeking van één adres weigert weergavenaamvormen zoals Aisha <aisha@example.com> in plaats van ze uit te pakken. Batchopzoekingen geven een beoordeling voor elke ingediende string.
Het deel vóór de @ wordt doorgegeven zoals geschreven in plaats van naar kleine letters omgezet, en het veld email behoudt dat hoofdlettergebruik. Batchantwoorden verwijderen omringende witruimte; koppel elk resultaat aan de invoer op dezelfde positie. Stuur het adres in het hoofdlettergebruik zoals je het hebt in plaats van het eerst te normaliseren: result is over het algemeen hetzelfde, maar delivery_confidence is niet altijd identiek, dus het wijzigen van het hoofdlettergebruik kan het antwoord veranderen.
De vijf oordelen
result is het veld om op te beslissen.
valid: het adres bestaat en accepteert mail. Verstuur.
neutral: het kon niet bevestigd worden, meestal omdat het ontvangende domein elke ontvanger hetzelfde beantwoordt. Versturen is redelijk; een neutraal adres is geen slecht adres, het is een onbeantwoordbaar adres.
risky: het accepteert waarschijnlijk mail, maar de kans op een bounce of klacht is groter dan gemiddeld. Roladressen, wegwerpadressen en adressen met een lage reputatie komen hier terecht. Of je verstuurt is een afweging op basis van je eigen tolerantie voor klachten, en flags vertelt je om welk soort risico het gaat.
undeliverable: het accepteert geen mail. Niet versturen. reason geeft de reden: invalid_syntax voor een misvormd adres, invalid_domain wanneer het domein helemaal geen mail accepteert, invalid_recipient wanneer het domein mail accepteert maar deze mailbox niet bestaat.
typo: het adres lijkt verkeerd gespeld, en did_you_mean bevat de correctie. Bied de correctie aan degene die het origineel typte aan in plaats van er ongevraagd naartoe te sturen: het is een gok, en het adres dat ze bedoelden kan geen van beide zijn.
result is een open vocabulaire, dus een waarde die je niet herkent is een toekomstig oordeel, geen fout. Vertrek vanuit de waarden die je kent en val terug op delivery_confidence, dat altijd aanwezig en altijd vergelijkbaar is.
Lees de betrouwbaarheidsscore naast het oordeel, niet in plaats ervan
delivery_confidence loopt van 0 (zeker niet afgeleverd) tot 100 (zeker wel). Dezelfde score kan om verschillende redenen onder neutral of risky vallen, dus het is een tweede mening en geen vervanging voor result. Het is het veld om op te steunen als je één drempelwaarde wilt voor alle oordelen, inclusief oordelen die later worden toegevoegd.
valid bevat de geldigheidsbeoordeling van de provider. Een ongeldige ontvanger kan valid: false hebben, zelfs als het domein mail accepteert. Gebruik result en delivery_confidence samen bij je beslissing of je verstuurt; valid: true garandeert geen aflevering.
Flags beschrijven het type adres
flags is leeg als er niets bijzonders van toepassing is. Er zijn drie waarden gedefinieerd, en het is een open lijst.
role betekent dat het adres een functie benoemt in plaats van een persoon, zoals support@ of info@. Antwoorden en toestemming zijn dubbelzinnig, en klachten zijn waarschijnlijker.
disposable betekent dat het bij een wegwerpadresprovider hoort, dus het zal doorgaans ophouden te bestaan.
free_provider betekent dat het bij een consumentenpostbusprovider hoort, zoals Gmail of Outlook.com. Dat is normaal voor consumentenmail, en alleen een signaal als je een zakelijk adres verwachtte.
Opnieuw proberen zonder dubbel te betalen
Elk beantwoord adres wordt gefactureerd, inclusief undeliverable, omdat dat het antwoord is waarvoor je betaalde en de bounce die je vermeed. Stuur een Idempotency-Key mee, zodat een herpoging het opgeslagen oordeel hergebruikt in plaats van een tweede te kopen. Zie Idempotentie.
De GET-vorm, die het adres in de URL plaatst, kan geen idempotentiesleutel meesturen. Gebruik de POST-vorm voor alles wat geautomatiseerd is.
Fouten
| Code | Wat er gebeurde |
|---|---|
| E22003 | Een opzoeking van één adres ontving een ongeldig e-mailadres. Er is niets in rekening gebracht. Batchopzoekingen beoordelen misvormde strings individueel en factureren die beoordelingen. |
| E22001 | De wallet van de organisatie dekt de opzoeking niet. Laad deze op en probeer opnieuw. Er is niets in rekening gebracht. |
| E22002 | Opzoeking is tijdelijk niet beschikbaar. Probeer opnieuw met backoff. Er is niets in rekening gebracht. |
Volgende stappen
- Een telefoonnummer opzoeken is de andere helft van Lookup.
- Suppressions voorkomen herhaalde verzendingen naar adressen die al gebounced zijn, zonder kosten.
- Lookup API-referentie documenteert elk veld.
- E-mail opzoeken: accepteert dat adres daadwerkelijk mail is een video die opzoekingen uitvoert tegen een roladres, een typfout en een gratis provider.
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.