Dockerized Email Verification API

I built a dockerized email verification REST API in Go, wrapping the open-source Reacher check-if-email-exists backend. It is useful for validating email syntax, MX records, SMTP reachability, disposable/role-account checks, and mailbox deliverability signals from a simple HTTP API.

Live API: https://emailcheck.halukaksoy.dev

Interactive Documentation

Full Scalar API documentation is available at:

https://emailcheck.halukaksoy.dev

The machine-readable OpenAPI spec is available at:

curl https://emailcheck.halukaksoy.dev/openapi.json

Import it into Postman, Insomnia, Bruno, or any OpenAPI-compatible client.

Check a Single Email

curl -X POST https://emailcheck.halukaksoy.dev/v1/check \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Example response:

{
  "email": "[email protected]",
  "result": {
    "input": "[email protected]",
    "is_reachable": "invalid",
    "misc": {
      "is_disposable": false,
      "is_role_account": false,
      "is_b2c": true
    },
    "mx": {
      "accepts_mail": true,
      "records": [
        "gmail-smtp-in.l.google.com."
      ]
    },
    "smtp": {
      "can_connect_smtp": true,
      "is_deliverable": false,
      "is_disabled": true,
      "has_full_inbox": false,
      "is_catch_all": false
    },
    "syntax": {
      "username": "someone",
      "domain": "gmail.com",
      "is_valid_syntax": true,
      "suggestion": null
    }
  }
}

The result object is returned directly from Reacher, so you get the full verification payload without the Go wrapper hiding useful details.

Batch Email Checks

You can check multiple emails in one request:

curl -X POST https://emailcheck.halukaksoy.dev/v1/check/batch \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]"
    ]
  }'

The default maximum batch size is 25 emails.

SOCKS5 Proxy Support

SMTP checks often require outbound port 25 access. If your server or network blocks SMTP traffic, you can pass a SOCKS5 proxy through the request body.

curl -X POST https://emailcheck.halukaksoy.dev/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "proxy": {
      "host": "my-proxy.example.com",
      "port": 1080,
      "username": "user",
      "password": "pass"
    }
  }'

The proxy payload is forwarded to Reacher.

Health Check

curl https://emailcheck.halukaksoy.dev/healthz

Response:

{
  "status": "ok"
}

Timeout Behavior

Email deliverability checks can be slow because they depend on DNS and SMTP server behavior. If the backend cannot complete verification within the configured timeout, the API returns:

504 Gateway Timeout

{
  "error": "email verification backend timed out"
}

For local testing, use curl -i so headers and status codes are visible:

curl -i --max-time 35 -X POST https://emailcheck.halukaksoy.dev/v1/check \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Rate Limiting

The API allows 60 requests per minute per IP. Rate limit state is tracked with a fixed-window algorithm. Responses include standard headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1746392460

When the limit is exceeded, you get a 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

Privacy

The API does not keep request logs or store checked email addresses. Requests are forwarded to the Reacher backend for verification and the result is returned directly to the client.

Dockerized Setup

The project runs as two containers:

• A Go API wrapper
• The Reacher backend container

The public API listens on port 8183 locally:

docker compose up --build

curl http://localhost:8183/healthz

Scalar docs are available locally at:

http://localhost:8183

Important SMTP Note

Reacher performs real SMTP-level checks. For full deliverability verification, the host running Docker needs outbound SMTP access, especially port 25.

If port 25 is blocked by your ISP, hosting provider, firewall, or cloud environment, checks may timeout or return incomplete results. In that case, run the service on a server with SMTP access or use an SMTP-capable SOCKS5 proxy.

Quick Endpoint Reference

Full interactive documentation with a built-in try-it panel: https://emailcheck.halukaksoy.dev