Repository: Billionmail/BillionMail

Stars: 13982

CLAUDE.md Copy Chapter

BillionMail

Open-source email marketing platform & mail server. Handles bulk sending, campaigns, contact management, warmup, and analytics.

Project Structure Copy Chapter

core/
├── internal/
│   ├── cmd/            # CLI entry points
│   ├── controller/     # HTTP handlers (16+ domains)
│   ├── service/        # Business logic (batch_mail, domains, rbac, maillog_stat, warmup, contact, etc.)
│   ├── dao/            # Data access layer
│   ├── model/entity/   # ORM entities
│   └── consts/         # Constants
├── api/                # API route definitions
├── frontend/src/
│   ├── views/          # Page components
│   ├── components/     # Reusable UI components
│   ├── store/          # Pinia store modules
│   ├── api/modules/    # API client modules
│   ├── router/         # Vue Router + module routes
│   ├── hooks/          # Composables
│   ├── utils/          # Utilities (base, data, time, storage)
│   ├── features/       # Feature-specific components (EmailEditor)
│   └── i18n/           # Internationalization (en, zh, ja)
├── template/           # Email templates
└── manifest/           # Config/deployment
conf/                   # Mail service configs (postfix, dovecot, rspamd, redis)
Dockerfiles/            # Container definitions

Stack Copy Chapter

- Backend: Go 1.22, GoFrame v2, PostgreSQL, Redis
- Frontend: Vue 3, TypeScript, Pinia, Naive UI, Vitest, pnpm
- Mail: Postfix, Dovecot, Rspamd
- Deploy: Docker Compose

Organization Rules Copy Chapter

- Controllers → core/internal/controller/, one dir per domain
- Services → core/internal/service/, one dir per domain
- API routes → core/api/, one dir per domain
- Frontend views → core/frontend/src/views/, one dir per feature
- Tests → next to source files (_test.go, .test.ts)
- Single responsibility per file, descriptive names

Code Quality Copy Chapter

After editing ANY file, run:

Go

cd core && go vet ./... && gofmt -l .
Frontend

cd core/frontend && pnpm run lint

Fix ALL errors before continuing.

Testing Copy Chapter

Go (short mode, no DB required)

cd core && go test -count=1 -short ./internal/service/...
Frontend

cd core/frontend && pnpm test
Both

cd core && go test -count=1 -short ./internal/service/... && cd frontend && pnpm test

Bug Memory Rules Copy Chapter

- NEVER use bare domain for mail infrastructure (DNS, certs, DKIM, dedicated IPs). Always use public.FormatMX(domain) to get the mail hostname (e.g., mail.example.com).
- When adding new controllers, add the module name to the RBAC modules list in core/internal/service/middlewares/rbac.go.

Commands Copy Chapter

- /test - Run full test suite
- /fix - Lint + typecheck + auto-fix with parallel agents
- /commit - Quality checks + AI commit + push
- /update-app - Update deps + fix deprecations

README.md Copy Chapter

<div align="center">
<a name="readme-top"></a>
<h1><a href="https://www.billionmail.com/" target="_blank">BillionMail 📧</a></h1>

An Open-Source MailServer, NewsLetter, Email Marketing Solution for Smarter Campaigns Copy Chapter

[![][license-shield]][license-link] [![][docs-shield]][docs-link] [![][github-release-shield]][github-release-link] [![][github-stars-shield]][github-stars-link]

English | 简体中文 | 日本語 | Türkçe
</div>
<br/>

<div align="center">
<a href="https://trendshift.io/repositories/13842" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13842" alt="aaPanel%2FBillionMail | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</div>

What is BillionMail? Copy Chapter

BillionMail is a future open-source Mail server, Email marketing platform designed to help businesses and individuals manage their email campaigns with ease. Whether you're sending newsletters, promotional emails, or transactional messages, this tool will provide full control over your email marketing efforts. With features like advanced analytics, and customer management, you'll be able to create, send, and track emails like a pro.

!BillionMail Banner

Just 3 steps to send a billion emails!

Step 1️⃣ Install BillionMail: Copy Section

cd /opt && git clone https://github.com/aaPanel/BillionMail && cd BillionMail && bash install.sh

Step 2️⃣: Connect Your Domain Copy Section

Step 3️⃣: Build Your Campaign Copy Section

- Write or paste your email
- Choose list & tags
- Set send time or send now

<div align="center">
<a href="https://www.youtube.com/embed/UHgxZa_9jGs?si=0-f1B5hDtcWImvQv" target="_blank">
<img src="https://img.youtube.com/vi/UHgxZa_9jGs/maxresdefault.jpg" alt="" width="80%">
<br />
<img src="https://www.iconfinder.com/icons/317714/download/png/16" alt="YouTube" width="16"/>
<b>Watch on Youtube</b>
</a>
</div>

Other installation methods Copy Chapter

One-click installation on aaPanel Copy Section

Docker

cd /opt && git clone https://github.com/aaPanel/BillionMail && cd BillionMail && cp env_init .env && docker compose up -d || docker-compose up -d

Management script Copy Chapter

bm help

- View Login default info

bm default

- Show domain DNS record

bm show-record

- Update BillionMail

bm update

Live Demo Copy Chapter

Username: billionmail

Password: billionmail

WebMail Copy Chapter

BillionMail has integrated RoundCube, you can access WebMail via /roundcube/.

Why BillionMail? Copy Chapter

Most email marketing platforms are either expensive, closed-source, or lack essential features. BillionMail aims to be different:

✅ Fully Open-Source – No hidden costs, no vendor lock-in.
📊 Advanced Analytics – Track email delivery, open rates, click-through rates, and more.
📧 Unlimited Sending – No restrictions on the number of emails you can send.
🎨 Customizable Templates – Custom professional marketing templates for reuse.
🔒 Privacy-First – Your data stays with you, no third-party tracking.
🚀 Self-Hosted – Run it on your own server for complete control.

How You Can Help 🌟 Copy Chapter

BillionMail is a community-driven project, and we need your support to get started! Here's how you can help:

1. Star This Repository: Show your interest by starring this repo.
2. Spread the Word: Share BillionMail with your network—developers, marketers, and open-source enthusiasts.
3. Share Feedback: Let us know what features you'd like to see in BillionMail by opening an issue or joining the discussion.
4. Contribute: Once development begins, we'll welcome contributions from the community. Stay tuned for updates!

---

📧 BillionMail – The Future of Open-Source Email Marketing.

Issues Copy Chapter

If you encounter any issues or have feature requests, please open an issue. Be sure to include:

- A clear description of the problem or request.
- Steps to reproduce the issue (if applicable).
- Screenshots or error logs (if applicable).

Install Now: Copy Chapter

cd /opt && git clone https://github.com/aaPanel/BillionMail && cd BillionMail && bash install.sh

Install with Docker: (Please install Docker and docker-compose-plugin manually, and modify .env file)

cd /opt && git clone https://github.com/aaPanel/BillionMail && cd BillionMail && cp env_init .env && docker compose up -d || docker-compose up -d

Star History Copy Chapter


License Copy Chapter

BillionMail is licensed under the AGPLv3 License. This means you can:

✅ Use the software for free.
✅ Modify and distribute the code.
✅ Use it privately without restrictions.

See the LICENSE file for more details.

---

<!-- BillionMail official link -->
[docs-link]: https://www.billionmail.com/

<!-- BillionMail Other link-->
[license-link]: https://www.gnu.org/licenses/agpl-3.0.html
[github-release-link]: https://github.com/aaPanel/BillionMail/releases/latest
[github-stars-link]: https://github.com/aaPanel/BillionMail
[github-issues-link]: https://github.com/aaPanel/BillionMail/issues

<!-- Shield link-->
[docs-shield]: https://img.shields.io/badge/documentation-148F76
[github-release-shield]: https://img.shields.io/github/v/release/aaPanel/BillionMail
[github-stars-shield]: https://img.shields.io/github/stars/aaPanel/BillionMail?color=%231890FF&style=flat-square   
[license-shield]: https://img.shields.io/github/license/aaPanel/BillionMail