happydomain/happydeliver repository overview

⁠happyDeliver - Email Deliverability Tester 📨

An open-source email deliverability testing platform that analyzes test emails and provides detailed deliverability reports with scoring.

⁠🧩 Features

• Complete Email Analysis – SPF, DKIM, DMARC, BIMI, ARC, SpamAssassin, DNS, blacklists, content, and headers
• REST API – Create tests and retrieve reports easily
• LMTP Server – Seamless MTA integration
• Smart Scoring System – Grades from A → F based on weighted factors
• Database Storage – SQLite or PostgreSQL
• Fully Configurable – via environment variables or config file

⁠🚀 Quick Start (Recommended)

The all-in-one Docker image includes everything you need:

• Postfix MTA (port 25)
• authentication_milter
• SpamAssassin
• happyDeliver API (port 8080)
• SQLite (persistent storage)

⁠Run with Docker Compose

git clone https://git.nemunai.re/happyDomain/happyDeliver.git
cd happyDeliver

# Edit docker-compose.yml to set your domain
# Change HAPPYDELIVER_DOMAIN and HOSTNAME variables

docker-compose up -d\`\`\`

**Access:**
- API: [http://localhost:8080](http://localhost:8080)
- SMTP: `localhost:25`

### 2️⃣ Run Directly with Docker

\`\`\`bash
docker run -d \
  --name happydeliver \
  -p 25:25 \
  -p 8080:8080 \
  -e HAPPYDELIVER_DOMAIN=yourdomain.com \
  -e HOSTNAME=mail.yourdomain.com \
  -v $(pwd)/data:/var/lib/happydeliver \
  -v $(pwd)/logs:/var/log/happydeliver \
  happydeliver:latest

⁠🌐 Network & DNS Configuration

⁠Open SMTP Port (25)

sudo ufw allow 25/tcp
# or
sudo iptables -A INPUT -p tcp --dport 25 -j ACCEPT

⁠Example DNS Records

yourdomain.com. IN A 203.0.113.10
yourdomain.com. IN AAAA 2001:db8::10

No MX record is required if the same host serves both HTTP and SMTP.

⁠🧪 API Usage

Example:

# Create a test
curl -X POST http://localhost:8080/api/test

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "test-kfauqaao@localhost",
  "status": "pending"
}

⁠🧰 CLI Mode

You can analyze emails manually from the command line:

cat email.eml | ./happyDeliver analyze

Or specify recipient explicitly:

cat email.eml | ./happyDeliver analyze -recipient [email protected]

⁠📊 Scoring Criteria

⁠💶 Funding

This project is funded by NGI Zero Core⁠, established by NLnet Foundation⁠ with support from the European Commission’s Next Generation Internet⁠ program.

⁠⚖️ License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)

⁠🐳 Docker Tags

Source: git.nemunai.re/happyDomain/happyDeliver⁠