Since Notifuse 16.1, a Notifuse installation can run an SMTP bridge, an SMTP server that turns each message it receives into a transactional email. An application that already sends over SMTP, such as a Django or Rails app, an old PHP site or a cron script, keeps its mail library and changes only its SMTP settings and the body it sends. Notifuse then renders the email from your template, tracks it, records it in your logs and sends it through the workspace's email provider. It shipped as the SMTP relay and was renamed SMTP bridge in Notifuse 29.
How it works
The bridge doesn't forward an email your application wrote. The body of the message is the JSON payload the transactional API takes, with the workspace, the transactional notification to send, the contact and the template data. Notifuse reads it and sends that notification as if transactional.send had been called:
The contact is created or updated, and the email is rendered from the notification's template, in the contact's language when the template has a translation.
Opens and clicks are tracked as set on the notification, and as far as the contact's tracking consent allows.
The email leaves through the workspace's transactional email provider: Amazon SES, Mailgun, Mailjet, Postmark, SendGrid, SparkPost or SMTP.
It shows in Logs like any transactional email, with the deliveries, bounces and complaints the provider reports.
The send happens while the client waits, and it gets 250 once the provider has accepted the email, or a 554 reply that says what went wrong: an unknown notification, a missing contact.email, a missing permission, a template whose Liquid fails, a provider that refused the email.
The payload
The body of a password reset sent through the bridge:
{
"workspace_id": "acme",
"notification": {
"id": "password_reset",
"contact": {
"email": "jane@example.com",
"first_name": "Jane",
"language": "fr"
},
"data": {
"reset_url": "https://app.example.com/reset/8f2c"
}
}
}The recipient is contact.email: the sender and recipients of the SMTP envelope are ignored, and so is the message's own subject. The subject and the sender come from the template. email_options can override the subject and the sender's name, pick another sender of the transactional email provider with sender_id (since Notifuse 44), and add cc, bcc, reply_to and attachments, sent base64-encoded in the JSON.
The body can be plain text or application/json, on its own or as one part of a multipart message: the bridge takes the first plain-text or JSON part that parses as JSON.
Headers
Four headers of the message are used when the payload doesn't set the same field:
Cc and Bcc become the email's cc and bcc. Many mail libraries keep Bcc out of the message and put it in the envelope only, which the bridge ignores: set
bccin the payload instead.Reply-To becomes its reply-to address, even when the template has one of its own.
Message-ID becomes its
external_id, so a message retried with the same Message-ID is sent only once.
Setup
The bridge is off by default. The operator of the installation turns it on with environment variables, or in the setup wizard and the root user's System Settings:
SMTP_BRIDGE_ENABLED=truestarts it.SMTP_BRIDGE_PORTis the port it listens on, 587 by default.SMTP_BRIDGE_DOMAINis the host name it announces, and the one shown to your team.SMTP_BRIDGE_TLS_CERT_BASE64andSMTP_BRIDGE_TLS_KEY_BASE64hold the certificate and its key, base64-encoded.SMTP_BRIDGE_TLS, since Notifuse 29.4, sets the TLS mode:starttls,implicitoroff.
starttls makes the client upgrade the connection before it logs in, the usual setup on port 587. implicit speaks TLS from the first byte, for clients that expect SMTPS on port 465: set SMTP_BRIDGE_PORT=465 with it. off runs in plaintext, for a bridge behind a proxy that terminates TLS on a trusted network. Left unset, the mode is starttls when a certificate is given; without one, Notifuse refuses to start in production, so that it never takes API keys in clear. The old SMTP_RELAY_* names still work.
Authentication
Clients log in with AUTH PLAIN and an API key of the workspace:
The username is the key's API email: the prefix chosen when the key was created, followed by your API host, such as
shop@api.example.com.The password is the key's token.
The key must belong to the workspace named in the payload. Since Notifuse 39 it needs Transactional write, as on the API, and that alone is enough to send. Without Contacts write, a send stores nothing about the recipient beyond the address, and without Contacts read, a message with cc or bcc is refused. A removed key stops working at once, and five failed logins in a minute lock a username out until the minute has passed.
Django example
A Django app points its email settings at the bridge and sends the payload as the body:
# settings.py
EMAIL_HOST = "smtp.example.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "shop@api.example.com"
EMAIL_HOST_PASSWORD = os.environ["NOTIFUSE_API_KEY"]
# in the app
import json
from django.core.mail import send_mail
payload = {
"workspace_id": "acme",
"notification": {
"id": "password_reset",
"contact": {"email": user.email, "first_name": user.first_name},
"data": {"reset_url": reset_url},
},
}
send_mail("password_reset", json.dumps(payload, indent=2), None, [user.email])The subject and the recipient list are there because send_mail wants them; the bridge ignores both. json.dumps writes ASCII and indent=2 keeps the lines short, so Django sends the body as it is: the bridge reads a single-part body as raw JSON and decodes neither quoted-printable nor base64 there. For implicit TLS, set EMAIL_PORT = 465 and EMAIL_USE_SSL = True instead of EMAIL_USE_TLS.
Use cases
For an app you won't rewrite, such as an old PHP or Java app, an ERP or an internal tool, as long as you can edit its message body: change its SMTP host and its body, and its emails get your templates and your logs.
Several apps can send through one bridge, each with its own key, and every email then leaves through the same provider with the same branding.
An app that built its emails in code keeps sending over SMTP while its templates move out of the code into Notifuse, where the people who write them can edit them.
Not yet
The bridge can't relay a finished email, a message your app composed with its HTML and subject: the body has to be the JSON payload. A service that lets you edit its email template, such as Supabase Auth, works by writing that JSON as the template's content; one whose email body you can't change can't use the bridge. For Supabase Auth, use the Supabase integration instead, which sends its emails from your Notifuse templates.
AUTH PLAIN is the only login method offered: a client that only knows LOGIN or CRAM-MD5 can't log in.
MIME attachments, the files attached to the message, are ignored; send them base64-encoded in
email_options.attachments.The certificate is read when Notifuse starts, so a renewed one needs its base64 settings updated and a restart.
Getting started
Once the bridge is on, Settings → SMTP bridge shows its host, port and TLS mode. An owner creates an API key with Transactional write in Settings → Team & API keys. Then, on the Transactional page, click a notification's API command button: its SMTP tab gives the connection details and a payload ready to fill in. The installation guide covers the settings and the certificates, the transactional API documentation the payload and the permissions, and the API keys documentation how to scope a send-only key.
