Skip to content
Get API key

Find Email

GEThttps://api.envoapi.com/v1/emails/find

Find the email address of a person from first name, optional last name and a domain with EnvoAPI. Candidate addresses are generated and verified until one is valid, catch-all, disposable or the domain has no mail server. When the provider is at capacity the request fails with a retryable error and the Credits are refunded. Yahoo domains, including yahoo.com and other Yahoo country domains, ymail.com and rocketmail.com, are not currently supported: the request fails with HTTP 422 and the Credits are refunded.

Authorization headerReturns application/json
GET
/v1/emails/find
firstName
required

Required first name of the person.

string
>= 1 characters <= 64 characters /\p{L}/

Example

Jane
lastName

Optional last name. Without it only first-name addresses are tried.

string
>= 1 characters <= 64 characters /\p{L}/

Example

Doe
domain
required

Email domain to search, for example example.com.

string
>= 3 characters <= 253 characters /^[\p{L}\p{N}](?:[\p{L}\p{N}.-]*[\p{L}\p{N}])?$/

Example

example.com

The first common address pattern the mail server accepts. A catch-all domain accepts every address, so no address is returned. Searches that find nothing are charged.

Media typeapplication/json
object
data
required
object
email
required
Any of:
string
>= 3 characters <= 254 characters
status
required
string
Allowed values: found catch_all not_found no_mx
isCatchAll
required
boolean
isDisposable
required
boolean
candidatesChecked
required
integer
<= 16
verification
required
Any of:
object
mx
required
Any of:
string
<= 253 characters
status
required
string
Allowed values: valid invalid unverifiable
reason
required
string
Allowed values: accepted limited rejected catch_all no_mx disposable mx_error timeout spam_block
meta
required
object
creditCost
required
integer
<= 9007199254740991
Date
string
/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?:0[1-9]|[12][0-9]|3[01]) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} (?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9] GMT$/

Required response header.

Cache-Control
string
Allowed value: private, no-store

Required response header.

X-Request-Id
string
>= 1 characters <= 64 characters /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/

Required response header.

X-Credits-Remaining
integer
<= 9007199254740991

Required response header.

X-RateLimit-Limit
integer
<= 9007199254740991

Required response header.

X-RateLimit-Remaining
integer
<= 9007199254740991

Required response header.

X-RateLimit-Reset
integer
<= 9007199254740991

Required response header.

Every error returns the same body. The status and error.code tell you what went wrong. The Errors guide covers handling and retries.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request invalid_api_key insufficient_credits insufficient_scope account_suspended resource_not_found method_not_allowed not_acceptable unsupported_media_type email_unverifiable rate_limit_exceeded internal_error response_too_large upstream_error upstream_timeout
message
required
string
>= 1 characters <= 512 characters
retryable
required
boolean
details
required
Array<object>
<= 16 items
object
field
required
string
>= 1 characters <= 128 characters /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/
code
required
string
Allowed values: identifier_count unknown_parameter repeated_parameter invalid_format invalid_value too_long
message
required
string
>= 1 characters <= 512 characters
meta
required
object
requestId
required
string
>= 1 characters <= 64 characters /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/
Date
string
/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?:0[1-9]|[12][0-9]|3[01]) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} (?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9] GMT$/

Required response header.

Cache-Control
string
Allowed value: private, no-store

Required response header.

X-Request-Id
string
>= 1 characters <= 64 characters /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/

Required response header.

Statuserror.codeMeaning
400invalid_requestA parameter is missing or has a value we cannot use. Read error.details, fix the value and try again.
401invalid_api_keyYour API key is missing, wrong or switched off. Check it in your dashboard.
402insufficient_creditsYour account has no credits left. Top up, then send a new call. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
403insufficient_scope, account_suspendedYour account is suspended or cannot use this endpoint. Resolve the account or its access first.
404resource_not_foundNothing matched what you sent. Check it for typos. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
405method_not_allowedThe route exists, but the request used a method other than GET. Use the method shown at the top of this page. Also sends Allow.
406not_acceptableThe Accept header asks for a format we do not send. Ask for JSON with a supported Accept value.
415unsupported_media_typeThe request declared a media type we do not accept. Remove the body or use the documented media type.
422email_unverifiableYahoo mailboxes are not supported: addresses at yahoo.* domains, ymail.com and rocketmail.com cannot currently be verified or found. Check error.code for email_unverifiable. The request is not retryable and the Credits are refunded. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
429rate_limit_exceededToo many calls in a short time. Honor Retry-After; use bounded retries with backoff and jitter. Also sends X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
500internal_error, response_too_largeSomething failed on our side. Retry only when error.retryable is true. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
502upstream_errorA data source sent back something we could not use. Retry with bounded backoff. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
503Lookups are unavailable for a moment. Follow error.retryable, and Retry-After when it is present. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
504upstream_timeoutThe lookup ran out of time. Retry with bounded backoff. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.