inis17/sendmail repository overview

⁠sendmail - GO Mail Service

A lightweight HTTP service to send emails via any SMTP server (e.g. Gmail,
Outlook, Postfix). Designed to be minimal and easy to deploy with Docker.

It exposes a single API endpoint with a JSON payload:

POST /v1/send

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Test email",
  "body": "Hello sendmail",
  "attachments": [
    {
      "filename": "report.pdf",
      "content_type": "application/pdf",
      "content": "base64-encoded-file-content"
    }
  ]
}

Authentication is handled via a Bearer token. Attachments are optional — omit the field entirely to send a plain email.

⁠Installation

⁠1. Go

Clone the repo and build:

git clone https://github.com/inis17/sendmail-docker.git
cd sendmail-docker.git
go build -o sendmail main.go

Run the server:

SMTP_HOST=smtp.gmail.com \
SMTP_PORT=587 \
[email protected] \
SMTP_PASS=your-app-password \
API_TOKEN=mysecrettoken \
./sendmail

⁠2. Docker

Run:

docker run --rm -p 8080:8080 \
  -e SMTP_HOST=smtp.gmail.com \
  -e SMTP_PORT=587 \
  -e [email protected] \
  -e SMTP_PASS=your-app-password \
  -e API_TOKEN=mysecrettoken \
  inis17/sendmail

⁠3. Docker Compose

Example docker-compose.yml :

services:
  sendmail:
    image: inis17/sendmail
    ports:
      - "8080:8080"
    environment:
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - [email protected]
        # You can append _FILE to load from a file inside the container (e.

g. docker secrets)

• SMTP_PASS=yourapppassword
• API_TOKEN=mysecrettoken

⁠Usage

⁠Basic email

curl -X POST http://localhost:8080/v1/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mysecrettoken" \
  -d '{
        "from": "[email protected]",
        "to": ["[email protected]"],
        "subject": "Test",
        "body": "Hello from Test"
      }'

⁠Email with attachment

curl -X POST http://localhost:8080/v1/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mysecrettoken" \
  -d '{
        "from": "[email protected]",
        "to": ["[email protected]"],
        "subject": "Test with attachment",
        "body": "Hello, see the attached file",
        "attachments": [
          {
            "filename": "hello.txt",
            "content_type": "text/plain",
            "content": "'"$(base64 -w0 hello.txt)"'"
          }
        ]
      }'

Attachment fields:

Field │ Required │ Description ───────────────┼──────────┼─────────────────────────────────────────────── filename │ Yes │ Name of the file as it will appear to the │ │ recipient content_type │ No │ MIME type (e.g. application/pdf ). Defaults │ │ to application/octet-stream if omitted content │ Yes │ Base64-encoded file contents

You can generate the base64 content on the command line, e.g.:

base64 -w0 report.pdf

⁠Environment Variables

Variable │ Default │ Description
──────────────────┼─────────┼─────────────────────────────────────────────
SMTP_HOST │ (none) │ SMTP server hostname (e.g.
│ │ smtp.gmail.com )
SMTP_PORT │ 587 │ SMTP server port ( 587 for STARTTLS, 465
│ │ for implicit TLS, 25 for plain)
SMTP_USER │ (none) │ SMTP username (usually your email address)
SMTP_PASS │ (none) │ SMTP password or app password
SMTP_PASS_FILE │ (none) │ Path to file containing SMTP password
│ │ (overrides SMTP_PASS )
API_TOKEN │ (none) │ Bearer token for authentication
API_TOKEN_FILE │ (none) │ Path to file containing API token
│ │ (overrides API_TOKEN )
PORT │ 8080 │ HTTP listen port

⁠Limits

• Combined attachment size (decoded) is capped at 12 MB per request.
• Total HTTP request body is capped at 20 MB, to account for base64
overhead (~33%) plus JSON structure.
• Requests exceeding these limits are rejected with 413 Request Entity
Too Large or a 400 Bad Request validation error.

⁠Security Notes

• Use App Passwords when connecting to Gmail/Outlook.
• Always use HTTPS (behind a reverse proxy like Nginx or Caddy) if exposed
outside localhost.
• Keep your API_TOKEN long and random.

⁠Features

• Simple /v1/send endpoint
• Authentication via Bearer token
• Works with Gmail, Outlook, or any SMTP server
• Supports Docker secrets ( *_FILE ) • Attachment support via base64-encoded content (multipart/mixed MIME) • Basic request validation (email format, required fields, size limits)