API Reference

Integrate email validation into your applications

Authentication Verify Email Batch Verify Filters Account Methods

Base URL

https://api.pipbit.io/v1

All API endpoints are versioned. The current version is v1

Authentication

Authenticate your requests using one of the following methods:

Recommended Authorization Header
Authorization: Bearer YOUR_API_KEY
Query Parameter
https://api.pipbit.io/v1/verify?email=test@example.com&api_key=YOUR_API_KEY

Validation Methods

Choose the validation depth that fits your needs. Pass the method parameter to specify.

quick 1 credit

Fast syntax and MX record validation. Best for basic filtering.

  • Syntax validation
  • MX record check
  • Disposable detection
DEFAULT
standard 2 credits

Full validation including role detection and risk scoring.

  • Everything in quick
  • Role-based detection
  • Free provider check
  • Risk score (0-100)
smtp 10 credits

Deep SMTP verification with mailbox existence check.

  • Everything in standard
  • SMTP handshake
  • Mailbox existence
  • Catch-all detection

Endpoints

GET /v1/verify
Verify Single Email

Validate a single email address and get detailed deliverability results.

Parameters

Name Type Required Description
email string required Email address to verify
method string optional quick, standard (default), or smtp
detailed boolean optional Return full response with all fields
fields string optional Comma-separated list of fields to return

Example Request

curl "https://api.pipbit.io/v1/verify?email=john@gmail.com&method=standard" \ -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "email": "john@gmail.com",
  "state": "deliverable",
  "score": 95,
  "reason": "accepted_email"
}
{
  "email": "john.smith@gmail.com",
  "state": "deliverable",
  "score": 100,
  "reason": "accepted_email",
  "domain": "gmail.com",
  "user": "john.smith",
  "mx_record": "aspmx.l.google.com",
  "smtp_provider": "google",
  "disposable": false,
  "role": false,
  "free": true,
  "catch_all": false,
  "mailbox_full": false,
  "no_reply": false,
  "duration": 0.493
}
POST /v1/verify
Batch Verification

Submit multiple emails for batch verification. Returns a job ID for tracking progress.

Request Body

Name Type Required Description
emails array required Array of email addresses (max 50,000)
method string optional quick, standard (default), or smtp
callback_url string optional Webhook URL for completion notification

Example Request

curl -X POST "https://api.pipbit.io/v1/verify" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"emails": ["john@gmail.com", "jane@yahoo.com"], "method": "standard"}'

Response (202 Accepted)

{
  "id": "batch_abc123xyz",
  "status": "processing",
  "total_emails": 2,
  "message": "Batch verification job created successfully"
}
GET /v1/verify/{batch_id}
Check Batch Status

Get the status and progress of a batch verification job.

curl "https://api.pipbit.io/v1/verify/batch_abc123xyz" \ -H "Authorization: Bearer YOUR_API_KEY"
{
  "id": "batch_abc123xyz",
  "status": "completed",
  "total_emails": 2,
  "processed": 2,
  "percent_complete": 100,
  "valid": 1,
  "invalid": 0,
  "risky": 1,
  "download_url": "https://api.pipbit.io/v1/verify/batch_abc123xyz/results"
}
GET /v1/verify/{batch_id}/results
Download Batch Results

Download the complete results of a finished batch verification job.

curl "https://api.pipbit.io/v1/verify/batch_abc123xyz/results" \ -H "Authorization: Bearer YOUR_API_KEY"

Email Filters

Manage filters to automatically block or allow specific emails, domains, or IP addresses. Filtered items skip validation and save credits.

POST /v1/filters
Create Filter

Create a new filter rule to block or allow emails.

Request Body

Name Type Required Description
value string required Email, domain, or IP to filter
filter_type string required email, domain, or ip_address
action string required block or allow
reason string optional Note about why this filter exists
curl -X POST "https://api.pipbit.io/v1/filters" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"value": "spam-domain.com", "filter_type": "domain", "action": "block", "reason": "Known spam domain"}'
GET /v1/filters
List Filters

Retrieve all filters with optional filtering by type.

curl "https://api.pipbit.io/v1/filters?filter_type=domain" \ -H "Authorization: Bearer YOUR_API_KEY"
{
  "filters": [
    {
      "id": "filter_xyz789",
      "value": "spam-domain.com",
      "filter_type": "domain",
      "action": "block",
      "reason": "Known spam domain",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1
}
DELETE /v1/filters/{filter_id}
Delete Filter

Remove a filter by its ID.

curl -X DELETE "https://api.pipbit.io/v1/filters/filter_xyz789" \ -H "Authorization: Bearer YOUR_API_KEY"
GET /v1/account
Account & Usage

Get your account information, credit balance, usage stats, and rate limits.

curl "https://api.pipbit.io/v1/account" \ -H "Authorization: Bearer YOUR_API_KEY"
{
  "email": "you@company.com",
  "plan": "starter",
  "credits": {
    "available": 4500,
    "used": 500,
    "total": 5000
  },
  "rate_limit": {
    "per_minute": 60,
    "remaining": 58
  },
  "billing_period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

Error Codes

Code Status Description
200 OK Request successful
202 Accepted Batch job created and processing
400 Bad Request Invalid parameters or request body
401 Unauthorized Invalid or missing API key
402 Payment Required Insufficient credits
429 Too Many Requests Rate limit exceeded

Ready to get started?

Create an API key to start validating emails programmatically.

Get Started Free