Reference · Find emails

Find emails for people or businesses

POST /api/v1/find-contacts

Finds and checks emails. findEmail: a named person at a business (first name, last name and website). companyInbox: the business email (info@, office@ …). roleContact: the owner, only when the business names the owner on its own website.

Send up to 50,000 rows (or a listId). The job runs in the background: poll GET /api/v1/jobs/{id}, set webhookUrl, or send wait (up to 30 seconds) to get small jobs back finished.

Only emails that Work are delivered; the others come back with a plain reason and cost nothing.

Credits: 1 credit per email that Works (you only pay for emails that work (everything else is free)). Not found, not sure or "takes any name" results are free. Rows your account already got an answer for in the last 30 days are answered again for free (cached30d).

Body (JSON)

Name	Type	What it is
`listId`	integer	Run on a list you already have (from POST /api/v1/lists or a search) instead of `rows`.
`contactIds`	array of integer	With listId: only these rows (default: all rows of the list). up to 50,000
`name`	string	Name of the new list (shown in the app). Default: "API ()".
`action`	`"findEmail"` · `"companyInbox"` · `"roleContact"`	findEmail: a named person (first + last name + website). companyInbox: the business email (info@, office@ …). roleContact: the owner, only when the business names them on its own website. default `"findEmail"`
`rows`	array of objects	Up to 50,000 rows. up to 50,000
`rows[].company`	string	Business name.
`rows[].website`	string	Website (any form: https://acme.com, acme.com/contact, www.acme.com).
`rows[].domain`	string	Domain, if you have it instead of a website.
`rows[].firstName`	string
`rows[].lastName`	string
`rows[].fullName`	string	Used when first and last name are not given separately.
`rows[].jobTitle`	string
`rows[].email`	string	The email to check (verify).
`rows[].phone`	string
`rows[].city`	string
`rows[].state`	string
`rows[].country`	string	Two-letter country code, e.g. US, CA, GB.
`rows[].address`	string	Business address. For US businesses it decides which state rules apply.
`rows[].category`	string
`webhookUrl`	string	Public https URL we POST the result to when the job is done (see the webhooks guide).
`webhookSecret`	string	Optional: sign this webhook with your own secret instead of the account signing secret.
`wait`	integer	Seconds to wait for the job to finish before answering (0–30). Handy for Zapier, Make and Clay: small jobs come back done, with results. default `0`, 0–30

Example request

Shell

curl -X POST "https://moleman.io/api/v1/find-contacts" \
  -H "Authorization: Bearer $MOLEMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rows":[{"firstName":"Sarah","lastName":"Miller","website":"https://brightsmiledental.com"}],"wait":20}'

Example answer

JSON

{
  "jobId": 981,
  "listId": 377,
  "action": "findEmail",
  "status": "done",
  "livemode": true,
  "total": 1,
  "done": 1,
  "failed": 0,
  "creditsCharged": 1,
  "creditsHeld": 0,
  "message": null,
  "createdAt": 1762344000000,
  "finishedAt": 1762344014000,
  "results": [
    {
      "id": 4102,
      "company": "Bright Smile Dental",
      "domain": "brightsmiledental.com",
      "firstName": "Sarah",
      "lastName": "Miller",
      "fullName": "Sarah Miller",
      "jobTitle": null,
      "email": "sarah.miller@brightsmiledental.com",
      "result": "Works",
      "resultCode": "verified",
      "resultMeaning": "We checked it. This inbox is real, so you can send to it.",
      "emailStatus": "valid",
      "emailStatusText": "Works",
      "emailScore": 96,
      "resolveStatus": null,
      "resolveStatusText": null,
      "findStatus": "found",
      "findStatusText": "Found and checked",
      "emailType": null,
      "emailTypeText": null,
      "briefText": null,
      "briefLine": null,
      "briefRelevance": null,
      "extra": {}
    }
  ],
  "nextCursor": null,
  "queued": 1,
  "skipped": [],
  "cached30d": 0,
  "maxCreditsHeld": 1,
  "pollUrl": "/api/v1/jobs/981"
}

Errors

Status	Code	When
401	`missing_api_key`	The request has no API key.
401	`invalid_api_key`	The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted).
401	`revoked_api_key`	The API key was revoked on the API page. Revoking takes effect at once.
429	`rate_limited`	More than 120 requests in one minute with this key.
500	`server_error`	Something broke on our side. Nothing was charged for it.
400	`invalid_request`	A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path.
400	`invalid_json`	The body is not valid JSON.
409	`idempotency_in_progress`	A request with the same Idempotency-Key is still running.
422	`idempotency_key_reused`	The Idempotency-Key was already used in the last 24 hours with a different request.
400	`no_eligible_rows`	None of the rows can run this action (for example: no website or domain to find an email for, or no email to check).
402	`insufficient_credits`	The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.
404	`not_found`	The job or list does not exist, belongs to another account, or was deleted.
400	`invalid_webhook_url`	The webhook URL is not a public https address (private networks and other schemes are refused).
403	`wrong_key_mode`	A test key asked for something made with a live key, or the other way round. Test and live data never mix.