# reacherhq/check-if-email-exists architecture

> Architecture diagram of the GitHub repository reacherhq/check-if-email-exists, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reacherhq/check-if-email-exists
- Repository: https://github.com/reacherhq/check-if-email-exists

## Overview

The product is an email-address reachability checker, available as a Rust library, a direct-running CLI, and an HTTP backend. Its core workflow parses and normalizes an address, checks DNS/MX, probes the mail provider over SMTP or provider-specific methods, gathers metadata, and classifies reachability. The backend also exposes synchronous and bulk APIs, with queued work, throttling, persistence, and optional webhook delivery. Several bulk and provider-specific implementations are unsampled, so their internal links are omitted or marked unverified.

Main entry points: [`core/src/lib.rs`](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/lib.rs) (Library API), [`backend/src/worker/do_work.rs`](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/worker/do_work.rs) (Work processor), [`backend/src/http/mod.rs`](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/mod.rs) (HTTP routing), [`backend/src/http/v0/bulk`](https://github.com/reacherhq/check-if-email-exists/tree/master/backend/src/http/v0/bulk) (Bulk API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_cli["CLI<br/>[main.rs]"]
  node_library_api["Library API<br/>[lib.rs]"]
end

subgraph group_verification["Email verification"]
  node_syntax["Syntax checks<br/>[mod.rs]"]
  node_mx["MX lookup<br/>[mod.rs]"]
  node_smtp["SMTP verification<br/>[connect.rs]"]
  node_provider_methods["Provider methods<br/>[mod.rs]"]
  node_smtp_parser["SMTP response parsing<br/>[parser.rs]"]
  node_misc["Address metadata<br/>[mod.rs]"]
  node_breach_check["Breach lookup<br/>[haveibeenpwned.rs]"]
  node_result_model["Result model<br/>[input_output.rs]"]
end

subgraph group_backend["HTTP backend"]
  node_http_routes["HTTP routing<br/>[mod.rs]"]
  node_single_check["Single-check API<br/>[post.rs]"]
  node_bulk_api["Bulk API"]
  node_v1_api["Version 1 API"]
  node_config["Backend config<br/>[config.rs]"]
end

subgraph group_operations["Async operations"]
  node_queue_consumer["Queue consumer<br/>[consume.rs]"]
  node_work_processor["Work processor<br/>[do_work.rs]"]
  node_throttle["Request throttling<br/>[throttle.rs]"]
  node_storage[("Postgres storage<br/>[postgres.rs]")]
  node_bulk_results["Bulk results<br/>[mod.rs]"]
  node_sqs_worker["SQS worker<br/>[main.rs]"]
end

node_cli_user(("CLI user"))
node_api_client(("API client"))

node_cli_user -->|"runs"| node_cli
node_cli -->|"checks email"| node_library_api
node_api_client -->|"sends requests"| node_http_routes
node_http_routes -->|"routes to"| node_single_check
node_http_routes -->|"routes to"| node_bulk_api
node_http_routes -->|"routes to"| node_v1_api
node_single_check -->|"calls check"| node_library_api
node_library_api -->|"checks syntax"| node_syntax
node_library_api -->|"checks MX"| node_mx
node_library_api -->|"verifies mailbox"| node_smtp
node_library_api -->|"gathers metadata"| node_misc
node_library_api -->|"returns result"| node_result_model
node_mx -->|"uses domain"| node_syntax
node_smtp -->|"dispatches methods"| node_provider_methods
node_smtp -->|"parses responses"| node_smtp_parser
node_misc -->|"optionally checks"| node_breach_check
node_misc -->|"uses address details"| node_syntax
node_v1_api -->|"dispatches work"| node_work_processor
node_v1_api -->|"checks limits"| node_throttle
node_config -->|"configures adapter"| node_storage
node_config -->|"configures limits"| node_throttle
node_queue_consumer -->|"processes messages"| node_work_processor
node_work_processor -->|"checks email"| node_library_api
node_work_processor -->|"stores results"| node_storage
node_work_processor -->|"checks capacity"| node_throttle
node_bulk_api -.->|"uses job storage"| node_storage
node_bulk_api -.->|"submits jobs"| node_queue_consumer
node_bulk_api -.->|"serves results"| node_bulk_results
node_sqs_worker -.->|"dispatches work"| node_work_processor

click node_cli "https://github.com/reacherhq/check-if-email-exists/blob/master/cli/src/main.rs"
click node_library_api "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/lib.rs"
click node_syntax "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/syntax/mod.rs"
click node_mx "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/mx/mod.rs"
click node_smtp "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/connect.rs"
click node_provider_methods "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/mod.rs"
click node_smtp_parser "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/parser.rs"
click node_misc "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/misc/mod.rs"
click node_breach_check "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/haveibeenpwned.rs"
click node_result_model "https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/util/input_output.rs"
click node_http_routes "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/mod.rs"
click node_single_check "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/v0/check_email/post.rs"
click node_bulk_api "https://github.com/reacherhq/check-if-email-exists/tree/master/backend/src/http/v0/bulk"
click node_v1_api "https://github.com/reacherhq/check-if-email-exists/tree/master/backend/src/http/v1"
click node_config "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/config.rs"
click node_queue_consumer "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/worker/consume.rs"
click node_work_processor "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/worker/do_work.rs"
click node_throttle "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/throttle.rs"
click node_storage "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/storage/postgres.rs"
click node_bulk_results "https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/v0/bulk/results/mod.rs"
click node_sqs_worker "https://github.com/reacherhq/check-if-email-exists/blob/master/sqs/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_library_api,node_cli_user,node_api_client toneBlue
class node_syntax,node_mx,node_smtp,node_provider_methods,node_smtp_parser,node_misc,node_breach_check,node_result_model toneAmber
class node_http_routes,node_single_check,node_bulk_api,node_v1_api,node_config toneMint
class node_queue_consumer,node_work_processor,node_throttle,node_storage,node_bulk_results,node_sqs_worker toneRose
```

## Components

### Clients

- [CLI](https://github.com/reacherhq/check-if-email-exists/blob/master/cli/src/main.rs): `cli/src/main.rs`
- [Library API](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/lib.rs): `core/src/lib.rs`

### Email verification

- [Syntax checks](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/syntax/mod.rs): `core/src/syntax/mod.rs`
- [MX lookup](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/mx/mod.rs): `core/src/mx/mod.rs`
- [SMTP verification](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/connect.rs): `core/src/smtp/connect.rs`
- [Provider methods](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/mod.rs): `core/src/smtp/mod.rs`
- [SMTP response parsing](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/smtp/parser.rs): `core/src/smtp/parser.rs`
- [Address metadata](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/misc/mod.rs): `core/src/misc/mod.rs`
- [Breach lookup](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/haveibeenpwned.rs): `core/src/haveibeenpwned.rs`
- [Result model](https://github.com/reacherhq/check-if-email-exists/blob/master/core/src/util/input_output.rs): `core/src/util/input_output.rs`

### HTTP backend

- [HTTP routing](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/mod.rs): `backend/src/http/mod.rs`
- [Single-check API](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/v0/check_email/post.rs): `backend/src/http/v0/check_email/post.rs`
- [Bulk API](https://github.com/reacherhq/check-if-email-exists/tree/master/backend/src/http/v0/bulk): `backend/src/http/v0/bulk`
- [Version 1 API](https://github.com/reacherhq/check-if-email-exists/tree/master/backend/src/http/v1): `backend/src/http/v1`
- [Backend config](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/config.rs): `backend/src/config.rs`

### Async operations

- [Queue consumer](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/worker/consume.rs): `backend/src/worker/consume.rs`
- [Work processor](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/worker/do_work.rs): `backend/src/worker/do_work.rs`
- [Request throttling](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/throttle.rs): `backend/src/throttle.rs`
- [Postgres storage](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/storage/postgres.rs): `backend/src/storage/postgres.rs`
- [Bulk results](https://github.com/reacherhq/check-if-email-exists/blob/master/backend/src/http/v0/bulk/results/mod.rs): `backend/src/http/v0/bulk/results/mod.rs`
- [SQS worker](https://github.com/reacherhq/check-if-email-exists/blob/master/sqs/src/main.rs): `sqs/src/main.rs`

### Other components

- **CLI user**
- **API client**

## Connections

- CLI user → CLI: runs (evidence: `README.md`)
- CLI → Library API: checks email (evidence: `README.md`)
- API client → HTTP routing: sends requests (evidence: `README.md`)
- HTTP routing → Single-check API: routes to (evidence: `backend/src/http/mod.rs`)
- HTTP routing → Bulk API: routes to (evidence: `backend/src/http/mod.rs`)
- HTTP routing → Version 1 API: routes to (evidence: `backend/src/http/mod.rs`)
- Single-check API → Library API: calls check (evidence: `backend/src/http/v0/check_email/post.rs`)
- Library API → Syntax checks: checks syntax (evidence: `core/src/lib.rs`)
- Library API → MX lookup: checks MX (evidence: `core/src/lib.rs`)
- Library API → SMTP verification: verifies mailbox (evidence: `core/src/lib.rs`)
- Library API → Address metadata: gathers metadata (evidence: `core/src/lib.rs`)
- Library API → Result model: returns result (evidence: `core/src/lib.rs`)
- MX lookup → Syntax checks: uses domain (evidence: `core/src/mx/mod.rs`)
- SMTP verification → Provider methods: dispatches methods (evidence: `core/src/smtp/mod.rs`)
- SMTP verification → SMTP response parsing: parses responses (evidence: `core/src/smtp/connect.rs`)
- Address metadata → Breach lookup: optionally checks (evidence: `core/src/misc/mod.rs`)
- Address metadata → Syntax checks: uses address details (evidence: `core/src/misc/mod.rs`)
- Version 1 API → Work processor: dispatches work (evidence: `backend/src/http/v1/check_email/post.rs`)
- Version 1 API → Request throttling: checks limits (evidence: `backend/src/http/v1/check_email/post.rs`)
- Backend config → Postgres storage: configures adapter (evidence: `backend/src/config.rs`)
- Backend config → Request throttling: configures limits (evidence: `backend/src/config.rs`)
- Queue consumer → Work processor: processes messages (evidence: `backend/src/worker/consume.rs`)
- Work processor → Library API: checks email (evidence: `backend/src/worker/do_work.rs`)
- Work processor → Postgres storage: stores results (evidence: `backend/src/worker/do_work.rs`)
- Work processor → Request throttling: checks capacity (evidence: `backend/src/worker/do_work.rs`)
- Bulk API → Postgres storage: uses job storage
- Bulk API → Queue consumer: submits jobs
- Bulk API → Bulk results: serves results (evidence: `backend/src/http/v0/bulk/results/mod.rs`)
- SQS worker → Work processor: dispatches work
