# Transactional email Campaigns go to lists. Transactional email goes to one person, right now, because something just happened: a password reset, a receipt, an invitation, a "your export is ready". You write a `tx` template in Listmonk once, then send it from code with the data that fills in the blanks. # Sending one ``` python ok = listmonk.send_transactional_email( 'jane@example.com', template_id=3, template_data={'full_name': 'Jane Doe', 'reset_code': 'abc123'}, content_type='html', ) ``` [`send_transactional_email()`](../reference/send_transactional_email.md) needs a recipient and a template ID. The template must be a `tx` template, not a campaign template; Listmonk keeps the two kinds apart and the ID of a campaign template will not work here. `template_data` is any JSON-serialisable dict. `content_type` is `html`, `markdown`, or `plain` and defaults to `markdown`. `from_email` is optional and falls back to the sender configured on the server. The return value is `True` when Listmonk accepted the message. Delivery after that point (SMTP errors, bounces) shows up in the Logs section of the Listmonk admin rather than coming back to you. # Where the data goes Listmonk renders templates with Go's template engine, not Jinja. Inside a `tx` template your `template_data` is reachable as `.Tx.Data`, and the recipient's record as `.Subscriber`: ``` html
Hi {{ .Subscriber.FirstName }},
Your reset code is {{ .Tx.Data.reset_code }}.
``` A `tx` template can carry its own subject line, set when you create it; see [Templates](templates.md#campaign-templates-and-transactional-templates). # Plain-text twin, attachments, headers ``` python from pathlib import Path ok = listmonk.send_transactional_email( 'jane@example.com', template_id=4, template_data={'order_id': 1772}, content_type='html', altbody='Your order 1772 has shipped.', attachments=[Path('/invoices/1772.pdf')], email_headers=[{'X-Priority': '1'}], ) ``` `altbody` is the plain-text alternative for mail clients that prefer text. `attachments` is a list of `Path` objects; the files are read and sent inline as a multipart request, and a path that does not exist raises [ListmonkFileNotFoundError](../reference/errors.ListmonkFileNotFoundError.md#listmonk.errors.ListmonkFileNotFoundError) before anything is sent. Custom `email_headers` are a list of single-entry dicts, one header each, not one dict with many keys. # People who are not subscribers By default Listmonk will only send a transactional email to an address that already exists as a subscriber. That is fine for someone who signed up, but your app also emails people who have not: the colleague Jane just invited, the guest who bought one thing, the person who requested a password reset before finishing registration. The `subscriber_mode` argument handles this. ``` python # 'external': no lookup at all. Any address works. listmonk.send_transactional_email( 'guest@example.com', template_id=3, subscriber_mode='external', template_data={'name': 'Sam', 'reset_url': 'https://app.example.com/reset/abc'}, ) # 'fallback': look the subscriber up, but still send if they are not found. listmonk.send_transactional_email('maybe@example.com', template_id=3, subscriber_mode='fallback') ``` The catch with both modes: only `{ .Subscriber.Email }` is populated in the template, because there may be no subscriber record to read from. Anything else the template needs, including the person's name, has to travel in `template_data` and be read as `{{ .Tx.Data.