Email Append API - Demographics, Phones and Validation

Turn a name and a postal address into an email address, turn an email address into the household behind it, and check that any address or phone number you hold is still worth using. One flat row per address, person or number.

What this actor does

• Appends an email to a name and a postal address. Give it a list of names paired line by line with postal addresses and it returns the address matched to that person, with a match type saying whether the match was to the individual or only to the household. Both the four part and the three part spelling of an address are understood, so a pasted list still works.
• Returns the household behind an address. Demographics gives you age, gender, postcode, household income, net worth, home value, home owner status, length of residence, marital status, presence of children, education, occupation, life stage, financial segment, recency and spend history, and the interests the provider holds. Interests arrive as dozens of booleans and are collapsed to a list of the ones that matched, so the row stays readable.
• Validates deliverability and fixes typos. Validation returns the verdict, the numeric reason code under it, the domain category, the role account flag and a zero to ten engagement quality score. When an address failed only because of a spelling mistake, the corrected address is lifted onto its own column, so a list clean gives you the address you should actually use rather than a nested suggestion.
• Finds a person's other addresses. Alternate email returns the other addresses tied to the same person or household, each with its own match type. That is how a bounced work address turns back into a reachable one.
• Verifies phone numbers. Phone verification returns line type, carrier, status, prepaid flag, country and a zero to one hundred connected score that says whether the line is actually live. Filter to mobile lines to build a list you can text.
• Calls each route at the path it really answers on. Three of these routes sit under a versioned path and two answer at the root. The versioned spellings of the last two are refused at the edge before they reach the API, so every route is written out in full rather than assembled from a shared prefix.
• Keeps the key out of every log line. This provider accepts the key only as a request parameter, never as a header, so the actor makes sure the real request URL is never written to a log.
• Never charges for a miss. Only rows carrying a resolved result are billed.

Input

Field	What it does
mode	Validate, demographics, email append, alternate email or phone verification.
emails	Addresses to validate, profile or find alternates for.
ipAddresses	Optional signup IPs, in the same order, to add geography.
fullNames	Names to append an address to.
postalAddresses	Postal addresses, paired line by line with the names.
phones	Numbers to verify.
phoneCountry	Two letter country code for numbers without a prefix.
statuses	Keep only these verdicts.
domainTypes	Keep only these domain categories.
excludeRoleAccounts	Drop shared inboxes such as info and support.
minQualityScore	Keep only addresses at or above this engagement score.
lineTypes	Keep only these phone line types.
minConnectedScore	Keep only numbers at or above this connected score.
timeout	Seconds the provider may spend on one address.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave unresolved inputs out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "validate",
  "query": "jane.doe@example.com",
  "email": "jane.doe@example.com",
  "status": "safetosend",
  "statusCode": 50,
  "domain": "example.com",
  "domainType": "biz",
  "roleAccount": false,
  "qualityScore": 8,
  "correctedEmail": null,
  "emailCorrections": null,
  "ipCountry": "US",
  "ipStateProvince": "Massachusetts",
  "ipRoutingType": "fixed",
  "ipAddress": "99.110.204.1",
  "error": null,
  "raw": { }
}

Frequently asked questions

What is an email append?

An email append matches a person you already know by name and postal address to the email address that belongs to them. It is the reverse of enrichment: instead of starting from an address and asking who owns it, you start from a household record and ask how to reach it by email. Every result carries a match type, which is the part that matters. An individual match means the full name and the postal address both matched. A household match means only the surname and the address matched, so the address may belong to someone else at the same home.

What demographics come back from an email address?

Age, gender, postcode, household income, net worth, home market value, home owner status, length of residence, marital status, presence of children, education, occupation, life stage group and segment, financial group and segment, and recency, frequency and spend history for both online and offline purchasing. Alongside those, the provider holds interest flags across dozens of categories; this actor returns the ones that matched as a list rather than spreading dozens of mostly empty columns across the table.

What is the difference between the safe to send verdict and valid?

Safe to send means the address passed every check the provider runs and is backed by its deliverability guarantee. Valid means it passed most of them but the mailbox itself could not be confirmed, usually because the receiving server would not answer a probe. Both are usually mailable, but only one carries the guarantee. Invalid means bad syntax, a dead domain or a mailbox that does not exist. Trap means the address is real but likely to trip a spam filter, and unknown means the checks could not be finished at all.

Can it correct a mistyped email address?

Yes. When an address fails only because of a spelling error the provider returns a corrected version, and the actor lifts the first correction into a correctedEmail column with every suggestion kept in emailCorrections. That is the difference between throwing away a signup and recovering it: a person who typed a common misspelling of a large webmail domain is a real subscriber with one bad character.

What does the connected score on a phone number mean?

It is the provider's confidence, from zero to one hundred, that the line is currently connected and dialable, and it is available for United States numbers. Above seventy means high confidence the number is live. Below thirty means high confidence it is disconnected. It is a different question from whether the number is valid: a number can be perfectly well formed, correctly routed to a real carrier, and still belong to a line that was cut off two years ago.

How do I build a list I can text rather than call?

Run phone verification, set the line type filter to mobile, and set a minimum connected score of seventy. That leaves only numbers on mobile lines that the provider is confident are still live. The carrier and prepaid flag come back on every row, which is worth keeping: prepaid lines change hands far more often than postpaid ones, so a prepaid number that verified today is a weaker record than a postpaid one.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from AtData, which is the provider whose email intelligence API this actor calls, created on their dashboard. Your own plan, credit balance and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret. This provider accepts the key only as a request parameter and not as a header, so the actor makes sure the real request URL never reaches a log line.

How does this handle rate limits and spent credits?

Requests are spaced evenly across the minute so a long list does not bunch up against the limiter, and the pace is yours to set. A rate limit or server error response is retried with backoff, because it clears on its own. A rejected key and a spent quota are treated differently: this provider answers both with a bare line of text rather than a JSON object, so the actor reads the body as text first and reports the provider's own message rather than a parse failure, and it stops instead of burning retries on something waiting will not fix.

Why did every alternate email lookup come back empty?

Because that one route does not check the key. Four of the five lookups reject a bad key outright, but alternate email answers HTTP 200 with an empty body whether the provider genuinely knows no other address for that person or your key is simply not entitled to the route. There is no way to tell the two apart from the response, so the actor logs a warning when a whole run of alternate email lookups comes back empty. If that is unexpected, run the same key against the validation lookup, which will say plainly whether the key is being accepted.

What happens when a lookup matches nobody?

This provider answers a miss with a successful response carrying an empty body, not with an error. That is a real answer about the input, so the row is written with found: false and an error explaining which lookup came back empty, and the run continues. Misses are not charged for. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each address, person or phone number resolved into the dataset, and never for misses, for rows dropped by the filters, or for duplicates. Apify platform usage is included in the per-result price. Your own API provider's credit balance is separate and billed by them.

Keyword map

email append API, email appending service, reverse append, demographic append API, consumer data append, household income data, net worth data, identity resolution, email validation API, email verification, safe to send, spam trap detection, role account detection, email typo correction, alternate email lookup, phone validation API, phone verification, line type lookup, carrier lookup, mobile number detection, connected score, data hygiene, customer data enrichment, direct mail list building