krsahil8825/http-smtp-proxy repository overview

⁠HTTP SMTP Proxy

A lightweight FastAPI service that lets you send emails over a simple HTTP/JSON API instead of talking to SMTP directly. You send it your SMTP server details and the email content in one request, and it relays the message for you.

It's built for situations where you want another app, script, or platform (that only speaks HTTP) to send email without embedding SMTP credentials or an SMTP client library inside it.

⁠Why Use This Image

• No SMTP client needed in your app - just make an HTTP POST request with JSON.
• Bring your own SMTP server - Gmail, Outlook/Office365, Amazon SES, Mailgun, Zoho, or any standard SMTP provider works, since the server details are passed per-request.
• Sync or async sending - send immediately and wait for the result, or queue it and get an instant response.
• Full email support - plain text, HTML, CC/BCC, reply-to, custom headers, and file attachments (base64-encoded).
• TLS/SSL support - works with both STARTTLS and implicit SSL SMTP connections.
• Simple API key auth - protect the service with one or more API keys via environment variables.
• Small, production-ready container - multi-stage build, runs as a non-root user, minimal image size.

⁠Where to Use It

• Behind an internal service, backend, or automation tool that needs to send transactional or notification emails.
• As a self-hosted alternative to SaaS "email sending" APIs, when you already have SMTP credentials you want to use directly.
• In low-code/no-code platforms, webhook automations (n8n, Zapier-style self-hosted tools, etc.), or scripts that can call HTTP endpoints but can't easily do raw SMTP.
• As a sidecar/proxy container next to your main application in Docker Compose or Kubernetes, so your app never has to hold real SMTP credentials - it only holds an API key for this proxy.

⁠How It Works

1. You send a POST request to /send (synchronous) or /send_async (queued in the background).
2. The request body includes:
   • smtp_config - host, port, username, password, TLS/SSL flags, timeout
   • sender - the from-address used for the email
   • messages - a list of one or more emails to send (to/cc/bcc, subject, text/HTML body, headers, attachments)
3. The service authenticates the request using the Authorization header, connects to your SMTP server, builds the email (including attachments), and sends it.
4. You get back a JSON response with the send status.

⁠Authentication

Every request must include:

Authorization: Bearer your-api-key

The token type must match the ALLOWED_TOKEN environment variable, and the key must be listed in ALLOWED_API_KEYS.

⁠Endpoints

⁠Example Request Body

{
  "smtp_config": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "[email protected]",
    "password": "your-password",
    "sender": { "email": "[email protected]", "name": "Example Sender" },
    "use_tls": true,
    "use_ssl": false,
    "timeout": 10
  },
  "sender": { "email": "[email protected]", "name": "Example Sender" },
  "messages": [
    {
      "to": [{ "email": "[email protected]", "name": "Recipient" }],
      "subject": "Test message",
      "text_body": "Hello from the SMTP proxy",
      "html_body": "<p>Hello from the SMTP proxy</p>"
    }
  ]
}

⁠Example Responses

/send:

{ "message": "1 email's sent successfully, 0 failed.", "status": "success", "sent": 1 }

/send_async:

{ "message": "Email sending initiated in the background.", "status": "initiated", "queued": 1 }

⁠How to Run the Container

⁠Quick Start

docker run -d \
  --name http-smtp-proxy \
  --restart unless-stopped \
  -p 8000:8000 \
  -e ALLOWED_API_KEYS=mykey1,mykey2 \
  -e ALLOWED_TOKEN=Bearer \
  -e DEBUG=false \
  krsahil8825/http-smtp-proxy:latest

The API will be available at http://localhost:8000.

⁠Using an Env File

docker run -d \
  --name http-smtp-proxy \
  --restart unless-stopped \
  -p 8000:8000 \
  --env-file .env \
  krsahil8825/http-smtp-proxy:latest

⁠Docker Compose

version: "3.9"

services:
  http-smtp-proxy:
    image: krsahil8825/http-smtp-proxy:latest
    container_name: http-smtp-proxy
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - ALLOWED_API_KEYS=mykey1,mykey2
      - ALLOWED_TOKEN=Bearer
      - DEBUG=false

docker compose up -d

⁠Environment Variables

⁠Ports

• 8000 - the FastAPI/Uvicorn HTTP server. Map it to whatever host port you prefer, e.g. -p 8000:8000.

⁠Tags

• latest - most recent stable build
• Versioned tags (e.g. v1.0.0, 1.0) - pinned releases for reproducible deployments

⁠Notes & Troubleshooting

• 401 Unauthorized - check your Authorization header format and that the key/token match ALLOWED_API_KEYS / ALLOWED_TOKEN.
• Container exits immediately - make sure at least one of ALLOWED_API_KEYS or ALLOWED_TOKEN is set.
• Emails fail to send - double-check the SMTP host, port, credentials, and whether TLS or SSL is required by your provider.
• Need interactive docs - run with DEBUG=true temporarily to access /docs, but switch it back off before exposing the service publicly.
• SMTP credentials are supplied per-request in smtp_config, not baked into the image - the container itself only needs an API key for authenticating callers.

⁠Source & License

@github/qcialdotcom/httpsmtpproxy⁠