Integrations / Bugsink

Connect the documented Django SMTP backend to an optional SMTP Senpai account while keeping error tracking, notification generation and email delivery separate.

What this example covers

Bugsink documents SMTP for issue notifications and administrative messages. It also allows a dummy backend that intentionally disables email. The example below selects Django’s SMTP backend explicitly. An existing email service can be used instead; SMTP Senpai is an optional transport choice.

Start with an isolated Bugsink instance, an owned test mailbox and a sender domain already verified in your SMTP Senpai account. Keep customer events, real error payloads and production recipients out of the demonstration. Take the actual SMTP hostname and credentials from your account: the mailbox receiving an alert does not determine its outgoing SMTP host.

Configuration fragment

Add the following to the configuration generated for your isolated instance. The environment variable names beginning with MSP_ are names chosen for this example, not built-in Bugsink settings. Supply them through your normal secret-management mechanism; do not commit their values or print them in logs.

import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ["MSP_SMTP_HOST"]
EMAIL_HOST_USER = os.environ["MSP_SMTP_USERNAME"]
EMAIL_HOST_PASSWORD = os.environ["MSP_SMTP_PASSWORD"]
EMAIL_PORT = 2525
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
EMAIL_TIMEOUT = 15
DEFAULT_FROM_EMAIL = os.environ["MSP_VERIFIED_FROM_EMAIL"]

For MSP_VERIFIED_FROM_EMAIL, use an address on the sender domain verified in the sending account. Missing environment variables fail immediately rather than silently substituting placeholder credentials. Keep certificate and hostname verification enabled. STARTTLS and implicit TLS are different modes; EMAIL_USE_TLS and EMAIL_USE_SSL must not both be enabled.

The official Docker setup accepts the documented settings as environment variables and parses their values. If using Docker, follow its configuration conventions instead of assuming that the example-specific MSP_ variables are automatically recognized. Restart the applicable webserver and worker after a configuration change, following the deployment documentation.

What we actually tested

The laboratory used one demonstration user, team and project, synthetic exceptions only, a loopback HTTP listener and no customer events or production installation changes. Phone-home was disabled. The first notification was captured to a file; a separate new issue then exercised the real SMTP transport to one owned mailbox.

  • Native path: HTTP event ingestion returned 200; ingest.tasks.digest was observed in the task database; runsnappea processed it and alerts.tasks.send_new_issue_alert generated the notification.
  • Existing issue: a second synthetic event for the same open issue produced two stored events and one issue, with only one captured notification. This does not validate every grouping, regression or unmute scenario.
  • Transport: Django’s SMTP backend used authenticated STARTTLS on port 2525, without disabling certificate or hostname checks. One multipart notification was received and its Message-ID and DKIM result recorded privately. Bugsink’s backend did not append a copy to an email client’s Sent folder.
  • Controlled negative check: a direct Django backend call to an unused loopback port raised ConnectionRefusedError. This checked a visible connection failure; it did not test native retry, bounce handling or certificate rejection.

When switching the local template from eager tasks to a separate asynchronous queue, we initially received HTTP 500 because the separate snappea database had not been migrated. No event or issue was stored by that failed request. After initializing the separate database, the native path succeeded. Follow the database and worker instructions for your deployment; do not apply laboratory database commands blindly to production.

The workers and HTTP server were stopped after the trial, the temporary SMTP credential file removed, and the laboratory configuration restored to file capture. Port 587 remains a documented SMTP option; this Bugsink runtime trial used 2525. Docker, production load, retries, quotas, administrative mail, regressions and unmute notifications were not validated.

A bounded validation checklist

  1. Record the installed Bugsink and Python versions, deployment type, selected backend and TLS mode. Do not call an untested release compatible.
  2. Use one synthetic notification and one owned recipient. Check that the relevant alert is enabled and that its task is actually processed.
  3. Correlate the message identifier, SMTP server response and received message headers. A successful transport handoff alone does not prove receipt.
  4. Exercise a deliberate configuration failure in the isolated setup and confirm that it is visible. Restore the valid configuration; do not disable TLS or certificate checks to make the failure disappear.
  5. Remove temporary secrets and demonstration data when finished. Retain only redacted evidence and the exact limits of what was observed.

When an alert does not arrive

Check the stages separately: event ingestion, alert selection, task execution, SMTP submission and receiving-mailbox outcome. A direct backend test does not exercise alert generation, background workers, retries or every administrative email. Bugsink’s instance email limit and the sending account’s quotas are also separate controls. Check both before a trial.

The Docker EMAIL_LOGGING setting can log subjects and recipients. Use it only with demonstration data when needed and avoid publishing those logs. DNS authentication observations, SMTP acceptance and inbox placement are different measurements.

References and next step

For another release or deployment type, agree the intended notification path and repeat only the checks needed for that environment. This guide does not require changing an existing customer installation, purchasing a licence or replacing a working email provider.