- Docs
- API reference
- Find Email
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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Required first name of the person.
Example
JaneOptional last name. Without it only first-name addresses are tried.
Example
DoeEmail domain to search, for example example.com.
Example
example.comResponses
Section titled “Responses”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.
object
object
Headers
Section titled “Headers”Required response header.
Required response header.
Required response header.
Required response header.
Required response header.
Required response header.
Required response header.
Errors
Section titled “Errors”Every error returns the same body. The status and error.code tell you what went wrong. The Errors guide covers handling and retries.
object
object
object
object
Headers
Section titled “Headers”Required response header.
Required response header.
Required response header.
| Status | error.code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is missing or has a value we cannot use. Read error.details, fix the value and try again. |
| 401 | invalid_api_key | Your API key is missing, wrong or switched off. Check it in your dashboard. |
| 402 | insufficient_credits | Your 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. |
| 403 | insufficient_scope, account_suspended | Your account is suspended or cannot use this endpoint. Resolve the account or its access first. |
| 404 | resource_not_found | Nothing matched what you sent. Check it for typos. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
| 405 | method_not_allowed | The route exists, but the request used a method other than GET. Use the method shown at the top of this page. Also sends Allow. |
| 406 | not_acceptable | The Accept header asks for a format we do not send. Ask for JSON with a supported Accept value. |
| 415 | unsupported_media_type | The request declared a media type we do not accept. Remove the body or use the documented media type. |
| 422 | email_unverifiable | Yahoo 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. |
| 429 | rate_limit_exceeded | Too 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. |
| 500 | internal_error, response_too_large | Something 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. |
| 502 | upstream_error | A 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. |
| 503 | Lookups 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. | |
| 504 | upstream_timeout | The lookup ran out of time. Retry with bounded backoff. Also sends X-Credits-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |