Anymail FinderAnymail FinderAPI Documentation
PricingGet your API key

Bulk Email Search: Create with File Upload

Use this API endpoint to create a Bulk Email Search by uploading a file (CSV or Excel). The system determines the type of email search to perform based on the fields you map.

Endpoint

POST
https://api.anymailfinder.com
/v5.1/bulk/multipart

Pricing

This endpoint is free to use.

Credits are only charged when you download the results for the first time.

Duplicate searches within a month are not charged.

Authentication

Include your API key using the Authorization header.
Refer to the Authentication page for setup instructions.

Code example

curl -X POST "https://api.anymailfinder.com/v5.1/bulk/multipart" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@your-leads-file.csv" \
  -F "domain_field_index=0" \
  -F "first_name_field_index=1" \
  -F "last_name_field_index=2" \
  -F "file_name=tech_ceos"
Download sample file

Request parameters

Search type depends on the fields you map:
  • Find Person Email - map any one of:
    • person name (full_name_field_index, or first_name_field_index + last_name_field_index) and company (domain_field_index or company_name_field_index)
    • linkedin_url_field_index only
    • both - LinkedIn URL together with name + company
  • Find Decision Maker Email - map domain_field_index or company_name_field_index, and specify decision_maker_category.
  • Find Company Emails - map domain_field_index or company_name_field_index.
  • Verify Email - map email_field_index only.
Domain vs. company name:

domain_field_index produces the most accurate results - use it whenever you have it. If you only have a company name, use company_name_field_index and we'll try to resolve a domain from it. When both are provided, domain_field_index is used first.

Send as "multipart/form-data" in the POST body:

ParameterExample valueDescription
file
file 		"your-leads-file.csv"A CSV or Excel file containing your data. The first row is expected to contain headers unless has_header is set to false.
company_name_field_index
integer - optional		nullThe zero-based index of the column containing the company name.
decision_maker_category
string[] - optional
[
  "finance",
  "ceo"
]
One or more categories of decision maker to search for. See the full list of available categories. If multiple are provided, they are tried in order: the search returns the first category that resolves to a valid email and does not attempt the rest. You can also define your own categories in your search settings and pass the value shown there in the API value column.
domain_field_index
integer - optional		0The zero-based index of the column containing the domain.
email_field_index
integer - optional		nullThe zero-based index of the column containing the emails to validate.
file_name
string - optional		"tech_ceos"A label to identify the bulk search.
first_name_field_index
integer - optional		1The zero-based index of the column containing the first name.
full_name_field_index
integer - optional		nullThe zero-based index of the column containing the full name.
has_header
boolean - optional		trueWhether the first row of the file contains headers. Defaults to true. Set to false if the first row is data.
last_name_field_index
integer - optional		2The zero-based index of the column containing the last name.
linkedin_url_field_index
integer - optional		nullThe zero-based index of the column containing the LinkedIn URL.
webhook_url
string - optional		nullURL to receive a webhook notification when processing completes.

Response

200OK

Show less

The search has been successfully created and will process asynchronously.

  • If you specified a webhook URL, you will receive a notification when the search is completed.
  • Otherwise, use the Bulk Search Detail API endpoint to check the search status.
{
  "counts": {
    "failed": 0,
    "found_unknown": 0,
    "found_valid": 0,
    "not_found": 0,
    "total": 0
  },
  "created_at": "2025-01-08T13:25:36.457Z",
  "credits_needed": 0,
  "decision_maker_category": "finance,ceo",
  "file_name": "string",
  "id": "string",
  "paid": true,
  "started_running_at": "2025-01-08T13:25:36.457Z",
  "status": "queued"
}
PropertyTypeDescription
statusstringThe current status of the bulk search. Possible values:
  • queued: Bulk search is queued and awaiting processing.
  • running: Bulk search is currently being processed.
  • paused: Bulk search processing is temporarily paused.
  • completed: Bulk search processing is complete.
  • failed: Bulk search processing failed due to an error.
counts.failedintegerNumber of rows where the search failed.
counts.found_unknownintegerNumber of rows with risky emails found. Only applies to Verify Email bulks: searches stopped returning risky emails on 5 October 2026.
counts.found_validintegerNumber of rows with valid emails found.
counts.not_foundintegerNumber of rows where no email was found.
counts.totalintegerTotal number of rows in the search.
created_atstringThe datetime when the search was created.
credits_neededintegerThe maximum credits required to download the results. Duplicate searches within a month are not charged.
decision_maker_categorystring | nullThe decision maker categories specified during search creation. This is a comma-separated list.
file_namestringThe label provided to identify this search.
idstringUnique identifier for this bulk search.
paidbooleanIndicates whether this search was paid for.
started_running_atstring | nullThe datetime when the search started processing.

400Bad Request

401Unauthorized

Need Help?

Our team is experienced with APIs and is here to help.
Chat with us.