Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DataTalksClub/datamailer/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the Datamailer repository, installing dependencies, running the development server, and making your first authenticated API call — all against a local SQLite database with no AWS account required. The full SQS and SES send path can be exercised later through LocalStack once you’re comfortable with the basics.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.12 or later — Datamailer’s pyproject.toml sets requires-python = ">=3.12".
  • uv — the package manager used to install dependencies and run management commands. Install it with curl -LsSf https://astral.sh/uv/install.sh | sh or see the uv docs for your platform.
  • Docker (optional) — only needed if you want to run LocalStack to emulate AWS SQS and SES locally. The quickstart below does not require it.

​
Setup Steps

1

Clone the repository

Clone the Datamailer source repository and change into the project directory:
git clone https://github.com/DataTalksClub/datamailer.git
cd datamailer
2

Run make setup

The setup target copies the example environment file, installs Python dependencies with uv sync, and runs database migrations in one step:
make setup
Under the hood this runs:
cp .env.example .env   # only if .env does not already exist
uv sync
uv run python manage.py migrate
The default .env configures a local SQLite database and the Django console email backend, so no external services are needed at this stage.
3

Seed demo data

Populate your local database with organisations, audiences, clients, contacts, campaigns, transactional message history, and engagement events:
uv run python manage.py seed_demo_data
The command is idempotent — run it again after future migrations to refresh the demo data without duplicating records. It does not enqueue any SQS work or call SES.
seed_demo_data requires DEBUG=True and will refuse to run in a production environment where DEBUG=False.
4

Start the development server

make run
This runs uv run python manage.py runserver. The server starts on http://localhost:8000 by default.
5

Log in to the operator UI

Open http://localhost:8000/admin/login/ in your browser and sign in with the demo admin credentials:
FieldValue
Usernameadmin
Passwordadmin
The product UI uses Django staff authentication, so unauthenticated users are redirected to /admin/login/ automatically. Once logged in you can browse audiences, contacts, campaigns, and client/API key management.
Staff users can view transactional template keys and their required context fields at /templates/.
6

Explore the interactive API reference

Navigate to http://localhost:8000/api-docs/ to open the interactive OpenAPI reference. It includes copy-pasteable local curl examples, request/response bodies, common errors, and the full endpoint listing. The raw OpenAPI JSON is also available at /api-docs/openapi.json.

​
Demo API Keys

The seed_demo_data command creates three stable API keys that map to the seeded client applications. Use these keys in local curl examples or when exploring the API docs:
ClientIntegration NameAPI Key
dtc-coursesCourse platform transactionaldm_dtccourses_demo_transactional_email_key
dtc-newsletterNewsletter import/exportdm_dtcnews_demo_newsletter_import_export_key
asl-platformASL platform transactionaldm_aslplatform_demo_transactional_email_key
All client API endpoints under /api/... require a Bearer token in the Authorization header. Datamailer stores only a hash of each key and displays its safe dm_<prefix> identifier for support and audit trails.
These keys are seeded for local development only. In production you create named API keys from the client detail page in the operator UI. The raw key is shown once on creation and must be stored by the client application immediately.

​
Your First API Call

The /api/contacts/status endpoint is a good starting point — it returns a contact’s subscription, verification, validation, suppression, and sendability state for a given audience and client scope, and it requires no write permissions. 
curl http://localhost:8000/api/contacts/status \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key" \
  -G --data-urlencode "email=learner@example.com" \
     --data-urlencode "audience=dtc-courses" \
     --data-urlencode "client=dtc-courses"
If the contact does not exist yet in your local seed data the endpoint will return a not-found response, which is expected — try substituting one of the seeded contact emails such as alex.verified@example.com: 
curl http://localhost:8000/api/contacts/status \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key" \
  -G --data-urlencode "email=alex.verified@example.com" \
     --data-urlencode "audience=dtc-courses" \
     --data-urlencode "client=dtc-courses"
For the full API reference — including contact upsert, subscription management, CSV import/export, transactional sends, and contact history — see the interactive docs at /api-docs/ once your server is running.

​
Next Steps

Your local Datamailer instance is now running with demo data and a working API. When you’re ready to move toward a production deployment, see the Configuration reference for a complete guide to all environment variables, including how to wire up Postgres, SES, and SQS.

Build docs developers (and LLMs) love

Get started for freeTalk to us