Configuration#

Configuration of django-email-relay is done through the DJANGO_EMAIL_RELAY dictionary in your Django settings.

Depending on whether you are configuring the relay service or the Django app, different settings are available. Some settings are available for both, while others are only available for one or the other. If you configure a setting that does not apply, for instance, if you configure something related to the relay service from one of the distributed Django apps, it will have no effect. See the individual sections for each setting below for more information.

All settings are optional. Here is an example configuration with the default values shown:

DJANGO_EMAIL_RELAY = {
    "DATABASE_ALIAS": email_relay.conf.EMAIL_RELAY_DATABASE_ALIAS,  # "email_relay_db"
    "EMAIL_MAX_BATCH": None,
    "EMAIL_MAX_DEFERRED": None,
    "EMAIL_MAX_RETRIES": None,
    "EMPTY_QUEUE_SLEEP": 30,
    "EMAIL_THROTTLE": 0,
    "MESSAGES_BATCH_SIZE": None,
    "MESSAGES_RETENTION_SECONDS": None,
    "RELAY_HEALTHCHECK_METHOD": "GET",
    "RELAY_HEALTHCHECK_STATUS_CODE": 200,
    "RELAY_HEALTHCHECK_TIMEOUT": 5.0,
    "RELAY_HEALTHCHECK_URL": None,
}

DATABASE_ALIAS#

Component

Configurable

Relay Service

Yes βœ…

Django App

Yes βœ…

The database alias to use for the email relay database. This must match the database alias used in your DATABASES setting. A default is provided at email_relay.conf.EMAIL_RELAY_DATABASE_ALIAS. You should only need to set this if you are using a different database alias.

EMAIL_MAX_BATCH#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The maximum number of emails to send in a single batch. The default is None, which means there is no limit.

EMAIL_MAX_DEFERRED#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The maximum number of emails that can be deferred before the relay service stops sending emails. The default is None, which means there is no limit.

EMAIL_MAX_RETRIES#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The maximum number of times an email can be deferred before being marked as failed. The default is None, which means there is no limit.

EMPTY_QUEUE_SLEEP#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The time in seconds to wait before checking the queue for new emails to send. The default is 30 seconds.

EMAIL_THROTTLE#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The time in seconds to sleep between sending emails to avoid potential rate limits or overloading your SMTP server. The default is 0 seconds.

MESSAGES_BATCH_SIZE#

Component

Configurable

Relay Service

No 🚫

Django App

Yes βœ…

The batch size to use when bulk creating Messages in the database. The default is None, which means Django’s default batch size will be used.

MESSAGES_RETENTION_SECONDS#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The time in seconds to keep Messages in the database before deleting them. None means the messages will be kept indefinitely, 0 means no messages will be kept, and any other integer value will be the number of seconds to keep messages. The default is None.

RELAY_HEALTHCHECK_METHOD#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The HTTP method to use for the healthcheck endpoint. RELAY_HEALTHCHECK_URL must also be set for this to have any effect. The default is "GET".

RELAY_HEALTHCHECK_STATUS_CODE#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The expected HTTP status code for the healthcheck endpoint. RELAY_HEALTHCHECK_URL must also be set for this to have any effect. The default is 200.

RELAY_HEALTHCHECK_TIMEOUT#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The timeout in seconds for the healthcheck endpoint. RELAY_HEALTHCHECK_URL must also be set for this to have any effect. The default is 5.0 seconds.

RELAY_HEALTHCHECK_URL#

Component

Configurable

Relay Service

Yes βœ…

Django App

No 🚫

The URL to ping after a loop of sending emails is complete. This can be used to integrate with a service like Healthchecks.io or UptimeRobot. The default is None, which means no healthcheck will be performed.