# rohannagar/jmail architecture

> Architecture diagram of the GitHub repository rohannagar/jmail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohannagar/jmail
- Repository: https://github.com/rohannagar/jmail

## Overview

JMail is a dependency-free Java library for parsing, validating, and working with email addresses. The principal workflow is a caller submitting an address to JMail, which parses it and returns a validation result; callers can instead configure an EmailValidator with additional rules. Successful parsing produces an Email value with address-part accessors and normalization options. Other documented capabilities include IP-address validation, encoded display-name decoding, and optional disposable-domain checks. Relationships reflect the README and SOURCE INDEX references; unsampled implementations are represented only where the tree and references support them.

Main entry points: [`src/main/java/com/sanctionco/jmail/EmailValidator.java`](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/EmailValidator.java) (Email Validator), [`src/main/java/com/sanctionco/jmail/Email.java`](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/Email.java) (Parsed Email), [`src/main/java/com/sanctionco/jmail/JMail.java`](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/JMail.java) (JMail API), [`src/main/java/com/sanctionco/jmail/ValidationRules.java`](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/ValidationRules.java) (Built-in Rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Parsing and API"]
  node_jmail["JMail API<br/>[JMail.java]"]
  node_email["Parsed Email<br/>[Email.java]"]
  node_result["Validation Result"]
end

subgraph group_rules["Validation Rules"]
  node_validator["Email Validator"]
  node_validation_rules["Built-in Rules"]
  node_failure["Failure Reasons<br/>[FailureReason.java]"]
end

subgraph group_address["Address Features"]
  node_tld["Top-Level Domains"]
  node_ip["IP Validation"]
  node_normalization["Normalization Options"]
  node_normalization_builder["Options Builder"]
  node_case_option["Case Options<br/>[CaseOption.java]"]
  node_idn["IDN Conversion<br/>[IDNConverter.java]"]
  node_encoded_word["Encoded Names<br/>[EncodedWord.java]"]
end

subgraph group_integrations["Optional Sources"]
  node_disposable_source["Disposable Domains"]
  node_http_client["HTTP Client<br/>[HttpClient.java]"]
  node_dns["DNS Lookup<br/>[DNSLookupUtil.java]"]
  node_is_temp_mail["IsTempMail Source"]
  node_input_stream["Stream Source"]
end

node_caller(("Library Caller"))

node_caller -->|"submits address"| node_jmail
node_caller -->|"configures rules"| node_validator
node_jmail -->|"delegates validation"| node_validator
node_jmail -->|"parses address"| node_email
node_jmail -->|"returns result"| node_result
node_jmail -->|"validates IP"| node_ip
node_validator -->|"uses parser"| node_jmail
node_validator -->|"applies rules"| node_validation_rules
node_validator -->|"checks parsed email"| node_email
node_validator -->|"produces result"| node_result
node_validator -->|"reports failures"| node_failure
node_validation_rules -->|"checks address fields"| node_email
node_validation_rules -->|"checks TLD"| node_tld
node_validation_rules -->|"uses lookup"| node_dns
node_validation_rules -->|"checks domain"| node_disposable_source
node_email -->|"extracts TLD"| node_tld
node_email -->|"decodes display name"| node_encoded_word
node_email -->|"normalizes address"| node_normalization
node_email -->|"converts domain"| node_idn
node_normalization_builder -->|"builds options"| node_normalization
node_normalization -->|"selects casing"| node_case_option
node_disposable_source -->|"creates stream source"| node_input_stream
node_disposable_source -->|"creates API source"| node_is_temp_mail
node_disposable_source -->|"configures client"| node_http_client
node_is_temp_mail -->|"requests API data"| node_http_client

click node_jmail "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/JMail.java"
click node_email "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/Email.java"
click node_result "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/EmailValidationResult.java"
click node_validator "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/EmailValidator.java"
click node_validation_rules "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/ValidationRules.java"
click node_failure "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/FailureReason.java"
click node_tld "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/TopLevelDomain.java"
click node_ip "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/net/InternetProtocolAddress.java"
click node_normalization "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/NormalizationOptions.java"
click node_normalization_builder "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilder.java"
click node_case_option "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/CaseOption.java"
click node_idn "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/IDNConverter.java"
click node_encoded_word "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/mime/EncodedWord.java"
click node_disposable_source "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java"
click node_http_client "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/HttpClient.java"
click node_dns "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/dns/DNSLookupUtil.java"
click node_is_temp_mail "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/IsTempMailAPISource.java"
click node_input_stream "https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/InputStreamSource.java"

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_jmail,node_email,node_result toneBlue
class node_validator,node_validation_rules,node_failure toneAmber
class node_tld,node_ip,node_normalization,node_normalization_builder,node_case_option,node_idn,node_encoded_word toneMint
class node_disposable_source,node_http_client,node_dns,node_is_temp_mail,node_input_stream toneRose
class node_caller toneIndigo
```

## Components

### Parsing and API

- [JMail API](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/JMail.java): `src/main/java/com/sanctionco/jmail/JMail.java`
- [Parsed Email](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/Email.java): `src/main/java/com/sanctionco/jmail/Email.java`
- [Validation Result](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/EmailValidationResult.java): `src/main/java/com/sanctionco/jmail/EmailValidationResult.java`

### Validation Rules

- [Email Validator](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/EmailValidator.java): `src/main/java/com/sanctionco/jmail/EmailValidator.java`
- [Built-in Rules](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/ValidationRules.java): `src/main/java/com/sanctionco/jmail/ValidationRules.java`
- [Failure Reasons](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/FailureReason.java): `src/main/java/com/sanctionco/jmail/FailureReason.java`

### Address Features

- [Top-Level Domains](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/TopLevelDomain.java): `src/main/java/com/sanctionco/jmail/TopLevelDomain.java`
- [IP Validation](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/net/InternetProtocolAddress.java): `src/main/java/com/sanctionco/jmail/net/InternetProtocolAddress.java`
- [Normalization Options](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/NormalizationOptions.java): `src/main/java/com/sanctionco/jmail/normalization/NormalizationOptions.java`
- [Options Builder](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilder.java): `src/main/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilder.java`
- [Case Options](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/CaseOption.java): `src/main/java/com/sanctionco/jmail/normalization/CaseOption.java`
- [IDN Conversion](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/normalization/IDNConverter.java): `src/main/java/com/sanctionco/jmail/normalization/IDNConverter.java`
- [Encoded Names](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/mime/EncodedWord.java): `src/main/java/com/sanctionco/jmail/mime/EncodedWord.java`

### Optional Sources

- [Disposable Domains](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java): `src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java`
- [HTTP Client](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/HttpClient.java): `src/main/java/com/sanctionco/jmail/disposable/HttpClient.java`
- [DNS Lookup](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/dns/DNSLookupUtil.java): `src/main/java/com/sanctionco/jmail/dns/DNSLookupUtil.java`
- [IsTempMail Source](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/IsTempMailAPISource.java): `src/main/java/com/sanctionco/jmail/disposable/IsTempMailAPISource.java`
- [Stream Source](https://github.com/rohannagar/jmail/blob/master/src/main/java/com/sanctionco/jmail/disposable/InputStreamSource.java): `src/main/java/com/sanctionco/jmail/disposable/InputStreamSource.java`

### Other components

- **Library Caller**

## Connections

- Library Caller → JMail API: submits address (evidence: `README.md`)
- Library Caller → Email Validator: configures rules (evidence: `README.md`)
- JMail API → Email Validator: delegates validation (evidence: `src/main/java/com/sanctionco/jmail/JMail.java`)
- JMail API → Parsed Email: parses address (evidence: `src/main/java/com/sanctionco/jmail/JMail.java`)
- JMail API → Validation Result: returns result (evidence: `src/main/java/com/sanctionco/jmail/JMail.java`)
- JMail API → IP Validation: validates IP (evidence: `src/main/java/com/sanctionco/jmail/JMail.java`)
- Email Validator → JMail API: uses parser (evidence: `src/main/java/com/sanctionco/jmail/EmailValidator.java`)
- Email Validator → Built-in Rules: applies rules (evidence: `src/main/java/com/sanctionco/jmail/EmailValidator.java`)
- Email Validator → Parsed Email: checks parsed email (evidence: `src/main/java/com/sanctionco/jmail/EmailValidator.java`)
- Email Validator → Validation Result: produces result (evidence: `src/main/java/com/sanctionco/jmail/EmailValidator.java`)
- Email Validator → Failure Reasons: reports failures (evidence: `src/main/java/com/sanctionco/jmail/EmailValidator.java`)
- Built-in Rules → Parsed Email: checks address fields (evidence: `src/main/java/com/sanctionco/jmail/ValidationRules.java`)
- Built-in Rules → Top-Level Domains: checks TLD (evidence: `src/main/java/com/sanctionco/jmail/ValidationRules.java`)
- Built-in Rules → DNS Lookup: uses lookup (evidence: `src/main/java/com/sanctionco/jmail/ValidationRules.java`)
- Built-in Rules → Disposable Domains: checks domain (evidence: `src/main/java/com/sanctionco/jmail/ValidationRules.java`)
- Parsed Email → Top-Level Domains: extracts TLD (evidence: `src/main/java/com/sanctionco/jmail/Email.java`)
- Parsed Email → Encoded Names: decodes display name (evidence: `src/main/java/com/sanctionco/jmail/Email.java`)
- Parsed Email → Normalization Options: normalizes address (evidence: `src/main/java/com/sanctionco/jmail/Email.java`)
- Parsed Email → IDN Conversion: converts domain (evidence: `src/main/java/com/sanctionco/jmail/Email.java`)
- Options Builder → Normalization Options: builds options (evidence: `src/main/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilder.java`)
- Normalization Options → Case Options: selects casing (evidence: `src/main/java/com/sanctionco/jmail/normalization/NormalizationOptions.java`)
- Disposable Domains → Stream Source: creates stream source (evidence: `src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java`)
- Disposable Domains → IsTempMail Source: creates API source (evidence: `src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java`)
- Disposable Domains → HTTP Client: configures client (evidence: `src/main/java/com/sanctionco/jmail/disposable/DisposableDomainSource.java`)
- IsTempMail Source → HTTP Client: requests API data (evidence: `src/main/java/com/sanctionco/jmail/disposable/IsTempMailAPISource.java`)
