API Documentation

Integrate HeroBounce directly into your applications with our high-performance REST API.

Getting Started

The HeroBounce API allows you to programmatically validate emails. Authentication is done via the X-API-Key header.

Get your API Key

You need an API key to make requests. Sign up for free to get yours.

Endpoints

POST/validation/single

Validate a single email address in real-time.

Request Body

{
  "email": "john.smith@company.com"
}

Response

{
  "email": "john.smith@company.com",
  "status": "valid",
  "confidence": 0.95,
  "is_valid": true,
  "details": {
    "syntax_valid": true,
    "dns_valid": true,
    "smtp_valid": true,
    "smtp_code": 250,
    "domain": "company.com",
    "provider": "google",
    "is_disposable": false,
    "is_role_based": false,
    "has_spf": true,
    "has_dmarc": true
  },
  "catchall": {
    "is_catchall": false,
    "confidence": null
  },
  "ai_enhancement": {
    "used": false,
    "method": null
  },
  "performance": {
    "response_time_ms": 1523
  },
  "metadata": {
    "timestamp": 1768842156.42,
    "plan_tier": "pro",
    "features_used": {
      "catchall_detection": true,
      "ai_enhancement": true
    }
  }
}
POST/validation/bulk

Validate up to 1,000 emails in a single API request. Uses 1 credit per unique email (duplicates are free).

Request Body

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}

Response

{
  "total": 3,
  "valid_count": 2,
  "invalid_count": 1,
  "risky_count": 0,
  "duplicate_count": 0,
  "credits_used": 3,
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "is_valid": true,
      "confidence": 0.95
    },
    ...
  ]
}
POST/bulk/upload/preview

Upload a CSV file for high-volume validation (up to 10,000 emails per file). For larger lists, split into multiple files for faster parallel processing. This is a two-step process.

STEP 1

Upload Preview

Send multipart/form-data with the CSV in the file field.

// Response
{
  "upload_id": "uuid...",
  "filename": "list.csv",
  "columns": ["id", "email", "name"],
  "suggested_email_column": "email"
}
STEP 2

Confirm Processing

POST/bulk/upload/confirm

Confirm which column to use using the upload_id.

// Request
{
  "upload_id": "uuid...",
  "email_column": "email"
}
// Response
{
  "id": "job_uuid...",
  "status": "queued"
}

Code Examples

# Single email validation (POST method)
curl -X POST "https://herobounce.com/api/v1/validation/single" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Single email validation (GET method - simpler!)
curl -X GET "https://herobounce.com/api/v1/validation/single?email=test@example.com" \
  -H "X-API-Key: your_api_key_here"

# Bulk email validation (up to 1000 emails)
curl -X POST "https://herobounce.com/api/v1/validation/bulk" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user1@example.com", "user2@example.com"]}'

# Bulk CSV Upload (Step 1: Preview)
# Upload file to get upload_id
curl -X POST "https://herobounce.com/api/v1/bulk/upload/preview" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@/path/to/your/list.csv"

# Bulk CSV Upload (Step 2: Confirm)
# Use upload_id from Step 1
curl -X POST "https://herobounce.com/api/v1/bulk/upload/confirm" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "uuid-from-step-1", "email_column": "email"}'