# samirkoirala/ownsmtp architecture

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

- Interactive diagram: https://gitdiagram.com/samirkoirala/ownsmtp
- Repository: https://github.com/samirkoirala/ownsmtp

## Overview

OwnSMTP is a self-hosted HTTP gateway that accepts authenticated email requests, validates them, and relays them through a configured SMTP account. The main flow is HTTP client → FastAPI routes → API-key check and request validation → SMTP delivery → success or HTTP error. Readiness checks configuration without contacting SMTP. The source shows these runtime interactions; deployment files and tests are excluded.

Main entry points: [`email_gateway/api.py`](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/api.py) (API routes), [`email_gateway/mailer.py`](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/mailer.py) (SMTP mailer), [`email_gateway/config.py`](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/config.py) (Runtime settings), [`email_gateway/app.py`](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/app.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP runtime"]
  node_app["FastAPI app<br/>[app.py]"]
  node_api["API routes<br/>[api.py]"]
end

subgraph group_access["Access and settings"]
  node_security["API-key check<br/>[security.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_email["Email delivery"]
  node_schemas["Email contracts<br/>[schemas.py]"]
  node_mailer["SMTP mailer<br/>[mailer.py]"]
end

subgraph group_external["External systems"]
  node_environment["Environment"]
  node_smtp["SMTP server"]
end

node_client(("HTTP client"))

node_client -->|"sends HTTP"| node_app
node_app -->|"dispatches routes"| node_api
node_api -->|"checks key"| node_security
node_security -->|"loads settings"| node_config
node_api -->|"checks readiness"| node_config
node_config -->|"reads variables"| node_environment
node_api -->|"validates and responds"| node_schemas
node_api -->|"requests delivery"| node_mailer
node_mailer -->|"reads SMTP settings"| node_config
node_mailer -->|"reads email request"| node_schemas
node_mailer -->|"sends message"| node_smtp
node_smtp -->|"accepts or refuses"| node_mailer
node_api -->|"returns HTTP result"| node_client

click node_app "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/app.py"
click node_api "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/api.py"
click node_security "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/security.py"
click node_config "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/config.py"
click node_schemas "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/schemas.py"
click node_mailer "https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/mailer.py"

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_app,node_api,node_client toneBlue
class node_security,node_config toneAmber
class node_schemas,node_mailer toneMint
class node_environment,node_smtp toneRose
```

## Components

### HTTP runtime

- [FastAPI app](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/app.py): `email_gateway/app.py`
- [API routes](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/api.py): `email_gateway/api.py`

### Access and settings

- [API-key check](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/security.py): `email_gateway/security.py`
- [Runtime settings](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/config.py): `email_gateway/config.py`

### Email delivery

- [Email contracts](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/schemas.py): `email_gateway/schemas.py`
- [SMTP mailer](https://github.com/samirkoirala/ownsmtp/blob/main/email_gateway/mailer.py): `email_gateway/mailer.py`

### External systems

- **Environment**
- **SMTP server**

### Other components

- **HTTP client**

## Connections

- HTTP client → FastAPI app: sends HTTP
- FastAPI app → API routes: dispatches routes
- API routes → API-key check: checks key
- API-key check → Runtime settings: loads settings
- API routes → Runtime settings: checks readiness
- Runtime settings → Environment: reads variables
- API routes → Email contracts: validates and responds
- API routes → SMTP mailer: requests delivery
- SMTP mailer → Runtime settings: reads SMTP settings
- SMTP mailer → Email contracts: reads email request
- SMTP mailer → SMTP server: sends message
- SMTP server → SMTP mailer: accepts or refuses
- API routes → HTTP client: returns HTTP result