Skip to main content
POST
/
v2
/
validate_emails
Validate Emails
curl --request POST \
  --url https://api.minerva.io/v2/validate_emails \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "records": [
    "<string>"
  ]
}
'
{
  "api_request_id": "req_email456",
  "results": [
    {
      "email_address": "john.smith@gmail.com",
      "is_match": true,
      "email_validation_status": "valid",
      "email_last_seen": "2024-01-10T15:30:00.000000"
    },
    {
      "email_address": "jane.doe@example.com",
      "is_match": true,
      "email_validation_status": "valid",
      "email_last_seen": "2023-12-15T09:22:00.000000"
    },
    {
      "email_address": "invalid@nonexistent.com",
      "is_match": false,
      "email_validation_status": null,
      "email_last_seen": null
    }
  ],
  "request_completed_at": "2024-01-15T10:30:45.123456"
}

​
Quick Answer

How do I validate email addresses or check if they exist in Minerva? Use this endpoint to check if email addresses are valid and whether they exist in the Minerva database.Common questions this endpoint answers:
  • How do I validate email addresses?
  • How do I check if an email exists in the Minerva database?
  • How can I verify email validity before enriching?
  • How do I see when an email was last seen?
  • How can I filter my email list to only Minerva-known contacts?
  • How do I check email quality?
What you need: List of email addresses (up to 2000 per request).What you get back: For each email: whether it’s found in Minerva, validation status, and last seen timestamp.Common use cases:
  • Pre-validate emails before using resolve/enrich
  • Filter email lists to focus on known contacts
  • Check data freshness with last seen dates
  • Verify email quality and validity

​
Overview

The Validate Emails endpoint checks if email addresses exist in the Minerva database and provides validation status and last seen date information. This endpoint accepts a simple list of email address strings and returns match status, validation status, and last seen timestamps for each email. The endpoint automatically handles email normalization and will attempt to match both the original email and any sanitized versions against the Minerva database.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
application/json

​
Request Body

​
records
string[]
required
An array of email address strings to validate. Maximum 2000 email addresses per request.Each element in the array should be a simple email address string (e.g., “user@example.com”).

​
Response

​
Response Structure

​
api_request_id
string
Unique identifier for this API request
​
results
array
Array of validation results, one per input email
​
request_completed_at
string
ISO 8601 timestamp when the request was completed

​
Result Object

​
email_address
string
The original email address from the request
​
is_match
boolean
Whether this email address (or its sanitized version) was found in the Minerva database
​
email_validation_status
string
Validation status of the email address. Can be “valid”, “invalid”, “unknown”, or null if no match was found.
​
email_last_seen
string
ISO 8601 timestamp of when this email was last seen in the Minerva database. Returns null if the email was not found.
{
  "api_request_id": "req_email456",
  "results": [
    {
      "email_address": "john.smith@gmail.com",
      "is_match": true,
      "email_validation_status": "valid",
      "email_last_seen": "2024-01-10T15:30:00.000000"
    },
    {
      "email_address": "jane.doe@example.com",
      "is_match": true,
      "email_validation_status": "valid",
      "email_last_seen": "2023-12-15T09:22:00.000000"
    },
    {
      "email_address": "invalid@nonexistent.com",
      "is_match": false,
      "email_validation_status": null,
      "email_last_seen": null
    }
  ],
  "request_completed_at": "2024-01-15T10:30:45.123456"
}

​
Error Responses

​
400
Bad Request
Invalid input format
​
401
Unauthorized
Invalid or missing API key
​
404
Not Found
Endpoint only supports v2 API version (attempting to access via /v1 or other version will return this error)
​
413
Payload Too Large
More than 2000 email addresses in request. Error message: “Maximum number of records for /v2/validate_emails endpoint is 2000”
​
422
Unprocessable Entity
Invalid request structure. Possible error messages:
  • “Input data must be a JSON with a ‘records’ key”
  • “Input data must contain a ‘records’ key with a list of inputs”
  • “Input records must be a list of email addresses”
​
500
Internal Server Error
Unexpected server error

​
Notes

  • API Version: This endpoint only supports v2 (/v2/validate_emails)
  • Rate Limits: Maximum 2000 email addresses per request
  • Email Normalization: Email addresses are automatically sanitized and normalized. The endpoint will match against both the original email and sanitized versions
  • Match Priority: If multiple versions of an email match (original vs. sanitized), the endpoint returns the best match based on most recent email_last_seen date
  • Return Order: Results are returned in the same order as the input array
  • Use Case: Use this endpoint to verify email existence in Minerva’s database before using resolve or enrich endpoints
  • Database Matching: Emails are matched against the data_lake.email_validation table using MD5 hashes of lowercase email addresses