# Bulk Gmail Mailer

A production-grade, self-hosted application for sending **permission-based bulk
email through your own authenticated Gmail accounts**. Every send is a real
Gmail API (or Gmail SMTP/XOAUTH2) call — there is no simulated, mocked, or
fake "success" path anywhere in the sending pipeline. Delivery status
(`queued → submitted → accepted / temp_failed / perm_failed / suppressed /
bounced`) always reflects what Google's API/SMTP server actually returned.

> **Compliance first.** This tool is built for legitimate use cases where you
> have obtained consent or have an existing relationship with every recipient
> (e.g. customer invoices/receipts, newsletters to opted-in subscribers,
> internal/organizational mail). It is **not** designed for, and must not be
> used for, unsolicited spam. See [Compliance & responsible use](#compliance--responsible-use)
> below.

---

## Table of contents

1. [Feature overview](#feature-overview)
2. [Architecture](#architecture)
3. [Quick start with Docker (recommended)](#quick-start-with-docker-recommended)
4. [Google Cloud OAuth setup](#google-cloud-oauth-setup)
5. [Gmail API enablement](#gmail-api-enablement)
6. [Manual setup without Docker](#manual-setup-without-docker)
7. [PostgreSQL & Redis setup details](#postgresql--redis-setup-details)
8. [Running the Celery worker](#running-the-celery-worker)
9. [First-run workflow (12-step wizard walkthrough)](#first-run-workflow-12-step-wizard-walkthrough)
10. [Configuration reference (.env)](#configuration-reference-env)