Mail Jack

Lightweight Go-based HTTP service to send emails via providers (currently AWS SES).
It offers per-recipient tracking, synchronous responses, and structured JSON errors — all through a single endpoint.

---

✨ Features

• AWS SES provider (more coming soon)
• Synchronous API: returns actual send status per recipient
• Detailed logging — logs every request, response, and error in PostgreSQL for easy debugging and analytics
• Docker support for easy deployment
• Open source and self-hostable anywhere

---

🧩 Requirements

• Go 1.22+ (module sets 1.24.x toolchain)
• AWS SES configured (verified sender/domain)
• PostgreSQL (for email logs)

---

⚙️ Environment Variables

Variable	Description	Default
PORT	HTTP port	8080
EMAIL_PROVIDER	Email provider name (SES)	—
AWS_REGION	AWS region (e.g. us-east-1)	—
AWS_ACCESS_KEY_ID	AWS Access Key	—
AWS_SECRET_ACCESS_KEY	AWS Secret Key	—
MAIL_JACK_API_KEY	API key for securing HTTP requests. This prevents unauthorized access to your email service and protects against abuse/spamming. Only clients with this key can send emails through Mail Jack. The key must be passed in the X-API-KEY header for all API calls. Set this to a secure random string (e.g., use openssl rand -hex 32).	required
DATABASE_URL	PostgreSQL connection string. Mail Jack will automatically create the necessary tables (email_logs) on startup to store email delivery logs, including recipient details, status, and message IDs.	required

Format:

postgres://username:password@host:port/database?sslmode=require

---

🧱 Run Locally

go run ./cmd

---

🐳 Docker

Create a .env file with all variables (.sample.env available), then:

# Build the image
docker build -t mail-jack:latest .

# Run the container
docker run -d -p 8080:8080 --env-file .env mail-jack:latest

---

📬 API

POST /send-email

Headers

Content-Type: application/json
X-API-KEY: your_api_key

Body (JSON)

{
  "from": "[email protected]",
  "to": ["[email protected]", "[email protected]"],
  "subject": "Hello",
  "body": "Plain text body",
  "html": "<p>HTML body</p>",
  "ccEmails": ["[email protected]"]
}

✅ Success Response

{
  "status": "SUCCESS",
  "results": [
    {
      "email": "[email protected]",
      "status": "SUCCESS",
      "messageId": "010e0199b4711bc0-...",
      "error": ""
    }
  ]
}

❌ Error Responses

400 { "error": "Invalid request" }
401 { "error": "Invalid API key" }
500 { "error": "Internal server error" }

Example (curl)

curl -X POST http://localhost:8080/send-email   -H "Content-Type: application/json"   -H "X-API-KEY: your_secret_api_key"   -d '{"from":"[email protected]","to":["[email protected]"],"subject":"Hi","body":"Hello","html":"<p>Hello</p>"}'

---

🧪 Build & Run

# Build binary
go build -o mail-jack ./cmd

# Run
./mail-jack

---

🧭 Roadmap

• Basic HTTP server
• Send Email API (POST /send-email)
• Split SES calls per recipient
• PostgreSQL email logs
• Concurrent sending via goroutines
• Async sending via SQS
• Web UI for logs
• Webhooks for status updates
• Add rate limiter
• Retry and Failure mechanism

---

---

📜 License

MIT © Karan Hotwani

Connect with me:
LinkedIn • Twitter