Get running

Quick start

Start OwnSMTP with Docker Compose and submit a test message.

Before you begin

You need Docker with Compose, SMTP credentials from your provider, and a sender identity that provider authorizes.

1. Pull the image

bash

docker pull ghcr.io/samirkoirala/ownsmtp:1.1.2

2. Configure the service

Clone the repository, copy its example environment file, and create an API key of at least 32 characters.

bash

git clone https://github.com/samirkoirala/OwnSMTP.git
cd OwnSMTP
cp .env.example .env
openssl rand -hex 32

Put the generated key and your SMTP settings in .env. Never commit that file.

3. Start Docker Compose

bash

docker compose up -d

4. Check readiness

bash

curl --fail http://127.0.0.1:8000/readyz

A successful response means required configuration is present and the service is ready to accept requests.

5. Send a test email

bash

curl -X POST http://127.0.0.1:8000/v1/emails \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "from_email": "notifications@yourdomain.com",
  "from_name": "Your Company",
  "recipient_email": ["customer@example.com"],
  "subject": "Welcome",
  "body": "<h1>Welcome!</h1><p>Your account is ready.</p>",
  "body_type": "html",
  "reply_to": "support@yourdomain.com"
}'

6. Inspect the live API docs

Open http://127.0.0.1:8000/docs while the service is running. The page is unavailable when DISABLE_DOCS is enabled.