Datamailer reads all of its runtime configuration from environment variables, loaded at startup from aDocumentation 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.
.env file in the project root via python-dotenv. There are no hard-coded settings files to edit — copy the example file, fill in the values for your environment, and restart the server.
DEBUG=False; Datamailer will raise ImproperlyConfigured at startup if they are missing.
Django Core
The Django secret key used for cryptographic signing (sessions, CSRF tokens, etc.). Must be a long, random, unpredictable string in production.
Enables Django debug mode. Set to
False in production. Accepts 1, true, or yes (case-insensitive) as truthy values.Comma-separated list of hostnames that Django will serve. In production, include every domain name and IP address your deployment responds to.Example:
datamailer.example.com,10.0.0.5Comma-separated list of trusted origins for CSRF protection (required when serving the UI behind a reverse proxy with HTTPS). Include the scheme.Example:
https://datamailer.example.comDatabase
A dj-database-url connection string. SQLite is fine for local development. Use a Postgres URL for production.
| Environment | Example value |
|---|---|
| Local (SQLite) | sqlite:///db.sqlite3 |
| Production (Postgres) | postgres://user:password@host:5432/datamailer |
Email Sending
The Django email backend used for Django’s own outgoing mail (password reset emails for staff users, etc.). For production delivery through SES, set this to
django_ses.SESBackend or the appropriate boto3-backed backend.| Value | Use case |
|---|---|
django.core.mail.backends.console.EmailBackend | Local development — prints to stdout |
django.core.mail.backends.smtp.EmailBackend | Generic SMTP relay |
The default
From address for all outgoing email. Must be a verified sender identity in SES for production deployments.Public URL
The externally reachable base URL of your Datamailer deployment, without a trailing slash. Used to construct open-tracking pixel URLs, click-tracking redirect URLs, and unsubscribe links that are embedded in outgoing emails. The
.env.example default is http://localhost:3000; the code falls back to http://localhost:8000 only when the variable is absent entirely.Example: https://datamailer.example.comAWS Credentials & Region
The AWS region for SES and SQS resources.
AWS access key ID. Leave blank when running on an EC2 instance or Lambda with an attached IAM role — boto3 will pick up credentials from the instance metadata service automatically.
AWS secret access key. As with
AWS_ACCESS_KEY_ID, leave blank when using IAM roles.Override the AWS service endpoint URL. Set this to your LocalStack endpoint (typically
http://localhost:4566) when developing locally with emulated SQS and SES.Leave
AWS_ENDPOINT_URL blank in production. It is only intended for LocalStack or other local AWS-compatible endpoints during development and testing.Amazon SES
The name of the SES configuration set to attach to outgoing emails. Configuration sets enable SES to publish delivery, bounce, complaint, open, and click events to SNS topics, which Datamailer then consumes via SQS. Leave blank for local development without SES.
SQS Queue URLs
These variables provide the full SQS queue URLs for each Datamailer processing queue. They are required for any environment where you want actual email sending or event processing. Leave them blank for local development against a local server without the full send pipeline.Full URL of the SQS queue that receives transactional email send jobs. The
/api/transactional/send endpoint requires this to be set before it can enqueue work.Example: https://sqs.us-east-1.amazonaws.com/123456789012/transactional-emailFull URL of the SQS queue that receives campaign email send jobs.Example:
https://sqs.us-east-1.amazonaws.com/123456789012/campaign-emailFull URL of the SQS queue that receives processed email engagement events (opens, clicks, bounces, complaints) for writing back to Postgres.Example:
https://sqs.us-east-1.amazonaws.com/123456789012/email-eventsFull URL of the SQS queue that receives raw inbound SES webhook payloads from SNS before they are processed by the event Lambda worker.Example:
https://sqs.us-east-1.amazonaws.com/123456789012/ses-webhooksSQS Queue Names
Queue names are used in contexts where a name is required rather than a URL (for example, CloudFormation references or smoke scripts). They must match the names of the queues identified by theSQS_*_QUEUE_URL variables above.
The name of the transactional email SQS queue.
The name of the campaign email SQS queue.
The name of the SES webhooks SQS queue.
The name of the email events SQS queue.
API Docs
Override the base URL used in copy-pasteable
curl examples shown in the in-app interactive API reference at /api-docs/. Useful when you want the embedded examples to target a staging or remote server without changing the server’s own PUBLIC_BASE_URL. If not set, falls back to PUBLIC_BASE_URL.Example: https://staging.datamailer.example.comAdvanced Sending & Webhook Settings
Maximum number of SES send calls per second that the campaign Lambda worker will attempt. Raise this if your SES account has an increased sending rate limit; lower it if you see
ThrottlingException errors. Fractional values are accepted.Example: 14.0Controls how the
Override the default only when running integration tests against a real SNS topic in a non-
/webhooks/ses endpoint validates inbound SNS notification signatures.| Value | Behaviour |
|---|---|
strict | Full SNS signature verification — required for production |
mock | Skips verification — set automatically when DEBUG=True or during tests |
DEBUG environment.When
True, the /webhooks/ses endpoint will automatically respond to SNS SubscriptionConfirmation messages, completing the SNS-to-SQS topic subscription handshake. Leave False (the default) and confirm the subscription manually from the AWS console unless you are automating the wiring in a deployment script.Example: Local Development .env
This configuration uses SQLite, the console email backend, and no AWS services. It is the default produced by cp .env.example .env and is suitable for running the operator UI and exploring the API with demo data.