---
title: "LinkedIn to Best Email"
method: POST
path: "/linkedin_to_best_email"
tags: ["Get Valid Emails"]
---

# LinkedIn to Best Email

`POST /linkedin_to_best_email`

## Request

- Base URL: `https://api.moltsets.com/api/v1/tools`
- URL: `https://api.moltsets.com/api/v1/tools/linkedin_to_best_email`
- Auth: HTTP bearer

The LinkedIn to Email API finds the best available email address for any LinkedIn profile. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).

It returns a valid business email when one exists, and automatically falls back to a personal email if not, so you get a result whenever the data is available. The `type` field in the response tells you which kind was returned. Use this as your default LinkedIn-to-email enrichment endpoint when the type of email doesn't matter to you.

**Use this endpoint to:**
- Enrich LinkedIn-sourced leads with a working email address
- Maximise match rate across business and personal inboxes
- Fill contact records that only have a LinkedIn URL

**Fair Use Policy:**
This API is subject to our <a href="https://moltsets.com/fair-use-policy-enrichment/" target="_blank" rel="noopener">Fair Use Policy for Enrichment</a>.

**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.

## Headers

- `User-Agent` string, required

## Request body

- object
  - `linkedin_url` string: Single LinkedIn profile URL or slug.
  - `linkedin_urls` string[]: Batch of LinkedIn profile URLs or slugs, up to 100.

## Response `200`

Success

- object
  - `results` object
    - `email` string, nullable: Email address found, or null if not found.
    - `risk_score` 'A' | 'B' | 'C' | 'D' | 'F' | 'null', nullable: Send-safety grade for the mailbox — deliverability, NOT whether the address belongs to the person looked up. A=validated deliverable; B=known engagement (a past open/click/order proves a send landed without bouncing); C=catch-all domain, deliverability unknowable; D=hard negative (spam trap/abuse/do-not-mail, or a complaint sighting in the last 6 months); F=no signal. Precedence when signals disagree: D > A > B > C > F. Absent when a scoring lookup is degraded — treat a missing grade as F.
    - `type` 'business' | 'personal' | 'null', nullable: Whether the returned email is a business or personal address.
    - `last_validated_at` string, nullable: ISO 8601 timestamp of last validation, or null.
  - `status` 'ok' | 'not_found': `ok` when the lookup found data, `not_found` when it completed but matched nothing. A miss is still HTTP 200 and costs no tokens.
  - `metadata` Metadata: Per-call metadata. `fair_use` is always present on a tool call; the remaining fields appear only where they apply.
    - `fair_use` object: Fair Use Policy headroom for the record limits that apply to this call.
      - `records_remaining_5h` integer: Records you can still request in the current rolling 5-hour window.
      - `records_reset_5h` string, date-time: ISO 8601 timestamp when the 5-hour records window resets.
      - `records_remaining_1w` integer: Records you can still request in the current rolling 1-week window.
      - `records_reset_1w` string, date-time: ISO 8601 timestamp when the 1-week records window resets.
    - `tokens_used` integer: Tokens consumed by this call. `0` on a `not_found`. Present on token-bound (free) accounts only — accounts on an unlimited subscription omit it.
    - `tokens_remaining` integer: Token balance after this call. Present on token-bound (free) accounts only.
    - `personal_email_restricted` boolean: Present and `true` only when the call actually withheld personal-email data because the account does not have the personal-email surface. Read a missing personal email as a plan boundary, not as absent data.
    - `identity_hashes_restricted` boolean: Present and `true` only when the call stripped `business_email_sha256s` because the account is on the \$397 or \$997 plan. Read a missing SHA256 hash as a plan boundary, not as absent data.
    - `retry_after` integer: Seconds until the binding Fair Use window unlocks. Present on Fair Use 429s, and on a batch that returned partial results because items were dropped for Fair Use — the same value is sent as a `Retry-After` header.
    - `phone_tokens_used` integer: Phone tokens consumed by this call. `linkedin_to_mobile_phone` only; `0` on a `not_found`.
    - `phone_tokens_remaining` integer: Phone tokens remaining after this call. `linkedin_to_mobile_phone` only.

## Other responses

- `401`: Unauthorized
- `402`: Payment Required — insufficient tokens
- `403`: Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive
- `422`: Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values
- `429`: Too Many Requests — rate limit or Fair Use window exhausted
- `500`: Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.

---

[API](https://skmtc.dev/moltsets/apis/moltsets-api.md) - [All operations](https://skmtc.dev/moltsets/apis/moltsets-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moltsets/apis/moltsets-api/revisions/b116df68bd90?raw)