Appearance
Email
TiruPay can send transactional emails on behalf of your service for every significant event in the payment lifecycle — invoices, subscription changes, price-change consent requests, payment failures, and more. You control the SMTP relay, the visual branding, the copy, and the locale — TiruPay handles delivery, logging, and template fallback.
Besides these typed, templated sends, Bulk Email lets you send an ad-hoc, unbranded email to a customer segment for one-off operational notices (e.g. a data breach disclosure) rather than a payment-lifecycle event.
Admin-only
All email management — SMTP settings, templates, logs, and bulk sends — is admin-only. There are no user- or service-level email endpoints.
How Emails Work
Every outgoing email goes through the following steps:
- Type resolution — The event that triggers the email has an
EmailType(e.g.invoice,subscription_activated). This determines which template is looked up and which placeholders are expected. - Template lookup — TiruPay searches for the best-matching
EmailTemplatefor the type, locale, and service (see Template Resolution). - Placeholder substitution —
%placeholder%tokens in the template body and footer are replaced with real values (e.g.%user_name%→"Jane Doe"). - HTML rendering — The substituted body is wrapped in a styled layout that applies your service's branding (header image, brand color, footer).
- SMTP dispatch — The final HTML email is sent via the resolved SMTP configuration.
- Logging — Every delivery attempt is logged in an
EmailLogrecord, regardless of success.
SMTP Settings
An SMTPEmailSetting holds the credentials for one SMTP relay. A service can have multiple SMTP settings (e.g. one per environment or department). One is designated the default in the EmailSetting; individual templates can also be pinned to a specific SMTP setting.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
name | string | Human-readable label (internal only) |
email_from | string | The sender address used in the From header |
server | string | SMTP server hostname |
port | integer | SMTP server port (e.g. 587, 465) |
username | string | SMTP authentication username |
password | string | SMTP authentication password |
use_tls | boolean | Whether to use TLS |
service_id | string | The service this setting belongs to |
created_at | datetime | When this setting was created |
updated_at | datetime | When this setting was last updated |
Reduced list view
List endpoints return a reduced view (id, name, email_from, timestamps). The full object including server credentials is returned when fetching a single setting. Username and password are never returned.
Email Setting
Each service has exactly one EmailSetting, created automatically when the service is created. It is the central branding and routing configuration for all email delivery.
| Field | Type | Description |
|---|---|---|
header_image_file_id | string | null | File ID of an image shown at the top of every outgoing email |
footer_default_text | string | null | Default footer text appended to every email (can be overridden per template) |
default_smtp_email_setting_id | string | null | Default SMTP setting used when a template has no specific SMTP setting pinned |
The header_image_file_id must point to a file with category image. The image is included in the email via the public download endpoint (GET /files/{file_id}/download) and therefore does not require authentication to load.
Brand color
The service's color field (set on the Service object) is used as the header background color in outgoing emails. TiruPay automatically chooses a contrasting white or dark text color for readability. TiruPay-internal emails (password reset, 2FA, admin notifications) always use a neutral white header, regardless of the service color.
Email Templates
An EmailTemplate stores the subject line and HTML body for a specific email type and locale. Templates are the primary way to customize what gets sent.
Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
type | enum | The EmailType this template is for (see Email Types) |
locale | string | Locale code (e.g. en, de) |
subject | string | Email subject line |
content | string | HTML body fragment — the inner content, without the surrounding chrome |
footer_overwrite | string | null | When set, replaces the EmailSetting.footer_default_text for this template |
smtp_email_setting_id | string | null | Pins this template to a specific SMTP setting (overrides the service default) |
is_global | boolean | true for TiruPay-provided default templates; false for service-specific templates |
service_id | string | null | null for global templates; the owning service ID for service-specific templates |
created_at | datetime | When this template was created |
updated_at | datetime | When this template was last updated |
Global templates (is_global = true, service_id = null) are TiruPay-wide defaults; you can create and modify templates for your own service(s), but not the global ones.
Template Resolution
When TiruPay needs to send an email it looks up the template in this order:
- Service-specific template for the requested
type+locale+service_id - Service fallback — the template referenced in the service's
EmailFallbackrecord for this type (if one is configured) - Global template for the requested
type+locale - Global English template for the requested
type+locale = "en"
If none of the above exist, the email is not sent.
Seeding defaults
TiruPay ships English global templates for every email type. On a new instance they are seeded once, giving your admins a working baseline to customize from.
Placeholder System
Template bodies use %placeholder_key% tokens. Before sending, TiruPay replaces every token with the corresponding runtime value for the event. Each EmailType has a documented set of valid placeholders.
Default placeholders are available in every template:
| Placeholder | Description |
|---|---|
%user_name% | Full name of the recipient |
%user_email% | Email address of the recipient |
%service_name% | Name of the service |
%service_logo_url% | URL to the service logo image |
%current_date% | Date when the email is sent |
%current_year% | Year when the email is sent |
%locale% | Locale of the recipient |
%brand_color% | The service's brand color (hex code) |
%brand_text_color% | The recommended text color (black or white) for readability on the brand color |
Additional placeholders depend on the email type — for example, invoice emails also provide %invoice_number%, %invoice_amount%, %invoice_url%, etc. The full list per type is available via the API:
GET /admin/email/placeholders
Returns a map of every EmailType to its list of valid placeholders, including descriptions.
HTML Rendering
Template content is an HTML fragment — the body of the message. TiruPay wraps this fragment at send time in a full HTML email layout that provides:
- A header area with the service's
header_image(if set) or logo, displayed on a background colored with the service'scolor - The email body (
contentafter placeholder substitution), injected verbatim - A footer with the
footer_default_text(or the template'sfooter_overwriteif set) and a copyright line
This means templates do not need to include <html>, <head>, or <body> tags — only the inner content.
Email Fallbacks
An EmailFallback lets a service designate a catch-all template for a given EmailType. When a recipient's locale does not have a matching service-specific template, TiruPay uses the fallback template before reaching for the global default.
| Field | Type | Description |
|---|---|---|
service_id | string | The service this fallback belongs to (part of primary key) |
type | enum | The EmailType this fallback covers (part of primary key) |
email_template_id | string | null | The template to fall back to (null = use global defaults) |
Each service can have at most one fallback per EmailType.
Bulk Email
Bulk email sends an ad-hoc email to a customer segment — for operational notices (a data breach disclosure, a planned outage) rather than a payment-lifecycle event. Unlike typed emails, a bulk send has no EmailType: it is not run through template resolution or wrapped in your service's branding — the content you provide is sent exactly as written.
Segments
A bulk send targets exactly one segment:
| Segment | Value | Required field | Recipients |
|---|---|---|---|
| All Customers | all_customers | — | Every customer in scope |
| Article Buyers | article_buyers | article_id | Customers with a paid order for this article |
| Article Extension Buyers | article_extension_buyers | article_extension_id | Customers with a paid order for this article extension |
| PAYG Plan Buyers | payg_plan_buyers | payg_plan_id | Customers with a balance on this PAYG plan |
| Active Subscribers | active_subscribers | article_id | Customers with an active subscription to this article |
Only the segment's required field may be set — the others must be left unset. service_ids further restricts the segment to specific services; omit it to target every service you have access to.
Sending flow
- Preview the recipient count —
POST /admin/email/bulk/recipients/countreturns how many customers the segment currently resolves to, without sending anything. - Export recipients as CSV, if you'd rather send through an external tool —
POST /admin/email/bulk/recipients/export. - Send —
POST /admin/email/bulk/sendenqueues the send as a background job and returns ajob_idimmediately (202 Accepted).
Content
content_by_locale maps a locale code to {subject, html_body, fallback_body}. Every locale among the resolved recipients' own locales must have an entry — there is no silent fallback to a different locale. default_locale is used for a recipient whose own locale isn't covered, and must itself be a key in content_by_locale.
Attachments
attachments is a list of {file_id, overwrite_filename}, each referencing an already-uploaded File. overwrite_filename optionally renames the attachment for this send. A bulk email can only attach existing files — there is no way to upload raw bytes through this endpoint.
Email Logs
Every send attempt is recorded as an EmailLog regardless of whether it succeeded. Logs are the primary tool for debugging delivery issues.
| Field | Description |
|---|---|
id | Unique identifier |
email_template_id | The template that produced this email, or null for an untemplated send (e.g. bulk email) |
subject | Subject line of the sent email |
content | Raw template content at send time (before placeholder substitution and HTML wrapping) |
footer | Raw footer text at send time (before placeholder substitution) |
error | true if delivery failed |
error_message | Error details if error is true |
induced_by | ID of the user who triggered the action that caused the email |
smtp_email_setting_id | Which SMTP setting was used |
service_id | The service the email was sent for |
created_at | When the delivery was attempted |
| recipients | The recipient addresses of the email |
| attachments | The files sent with the email (see Logged Attachments below) |
Content is the raw template
content and footer store their raw values before placeholder substitution and, for typed emails, HTML wrapping. This is intentional — it makes the log useful for auditing and resending without replaying potentially stale runtime data.
Untemplated logs render unwrapped
When you fetch a rendered preview of a log with email_template_id = null (e.g. a bulk email), TiruPay returns the raw content as-is, with no branding wrapper — matching exactly what was sent. Only logs from a templated send are wrapped in your service's branding.
Logged Attachments
A sent email can carry file attachments, each recorded with a link to its File.
| Field | Type | Description |
|---|---|---|
file_id | string | null | The attached file, or null if the attachment wasn't sourced from an uploaded file |
overwrite_filename | string | null | Filename shown to the recipient, if different from the file's own name |
created_at | datetime | When the attachment was recorded |
file | object | The attached file's public metadata, when file_id is set |
Invoice and credit note emails automatically attach the generated PDF. Bulk emails can attach existing files explicitly (see Bulk Email).
Not every attachment is logged
An attachment is only recorded here when it's backed by an uploaded file. An invoice PDF fetched directly from an external invoicing provider at send time is still attached to the email itself, but does not appear in this list.
Email Types
Email types fall into two groups: types a service can override, and TiruPay-internal types.
Service-overwriteable types
Services can provide their own templates for all types in this group. If no service-specific template exists, the global default is used.
Documents
| Type | Value | Trigger |
|---|---|---|
| Invoice | invoice | An invoice is issued for an order |
| Dunning | dunning | A dunning reminder is sent for an unpaid invoice |
| Credit Note | credit_note | A credit note is issued |
Payments
| Type | Value | Trigger |
|---|---|---|
| Payment Method Failure | payment_method_failure | A payment method charge fails |
| Mandate Failure | mandate_failure | A SEPA/direct debit mandate fails |
| Mandate Payment Pending | mandate_payment_pending | A mandate payment is pending clearance |
| Refund Succeeded | refund_succeeded | A refund is processed successfully |
| Refund to Credit Balance | refund_to_credit_balance | A refund is credited to the customer's Credit Balance instead of the original payment method |
One-time Orders
| Type | Value | Trigger |
|---|---|---|
| Order Payment Reminder | order_reminder | An unpaid order still needs payment |
| Order Paid | order_paid | An order is successfully paid |
| Order Refunded | order_refunded | An order is fully refunded |
| Order Revoked | order_revoked | An order is revoked/cancelled |
Subscriptions
| Type | Value | Trigger |
|---|---|---|
| Subscription Activated | subscription_activated | A subscription is created and active |
| Free Tier Activated | free_tier_activated | A Free Tier subscription starts |
| Renewal Reminder | subscription_renewal_reminder | An upcoming renewal is approaching |
| Cancellation Notice | subscription_cancellation_notice | A subscription is cancelled |
| Paused Notice | subscription_paused_notice | A subscription is paused |
| Reactivated Notice | subscription_reactivated_notice | A paused subscription is reactivated |
| Upgrade Notice | subscription_upgrade_notice | A subscription is upgraded to a higher tier |
| Downgrade Notice | subscription_downgrade_notice | A subscription is downgraded to a lower tier |
| Termination Notice | subscription_termination_notice | A subscription reaches its end and terminates |
| Coupon Applied | coupon_applied_to_subscription | A subscription's recurring coupon is switched directly, taking effect at the next renewal |
| Coupon Removed | coupon_removed_from_subscription | A subscription's recurring coupon is removed directly, taking effect at the next renewal |
Trials
A Trial email has one type per thing that follows the Trial, so you can word each case on its own. TiruPay picks the type that matches the subscription.
| Type | Value | Trigger |
|---|---|---|
| Trial Started (then paid plan) | trial_started_convert | A Trial started that continues as a paid plan |
| Trial Started (then free plan) | trial_started_fallback | A Trial started that moves to the Free Tier |
| Trial Started (then ends) | trial_started_expire | A Trial started that simply ends |
| Trial Ending Soon (then paid plan) | trial_ending_soon_convert | Reminder before the end of a Trial that continues as a paid plan |
| Trial Ending Soon (then free plan) | trial_ending_soon_fallback | Reminder before the end of a Trial that moves to the Free Tier |
| Trial Ending Soon (then ends) | trial_ending_soon_expire | Reminder before the end of a Trial that simply ends |
| Trial Ended (now paid plan) | trial_ended_converted | A Trial ended and the plan continues as a paid plan |
| Trial Ended (now free plan) | trial_ended_fallback | A Trial ended and the customer is on the Free Tier |
| Trial Ended (access ended) | trial_ended_expired | A Trial ended and no plan follows |
A Trial set to move to the Free Tier gets the "then ends" types when its category has no Free Tier to move to. trial_ending_soon_convert also provides %price_after_trial%, the gross price of the first paid period.
Price Changes
| Type | Value | Trigger |
|---|---|---|
| Consent Required | price_change_consent_required | Customer consent is requested for a scheduled price change |
| Consent Warning | price_change_consent_warning | A reminder that the consent deadline is approaching (implies possible cancellation) |
| Consent Confirmation | price_change_consent_confirmation | Customer's acceptance of the price change is confirmed |
| No-Consent Confirmation | price_change_no_consent_confirmation | Customer's rejection is acknowledged (subscription may be cancelled) |
| No-Change Notice | price_change_no_change | Informs the customer that a price change they may have heard about will not affect them |
The consent_required and consent_warning types include a %price_change_consent_url% placeholder — a direct link to the TiruPay frontend where the customer accepts or declines.
Pay-as-you-go (PAYG)
| Type | Value | Trigger |
|---|---|---|
| PAYG Setup Confirmation | payg_setup_confirmation | A PAYG agreement is set up |
| PAYG Usage Alert | payg_usage_alert | Usage reaches the configured limit |
| PAYG Billing Notice | payg_billing_notice | A PAYG period is billed |
| PAYG Below Threshold | payg_below_threshold_notice | Usage occurred but stayed below the billing threshold — no charge |
| PAYG Problem | payg_problem | A PAYG billing cycle fails |
TiruPay-internal types
These types are managed entirely by TiruPay. Services cannot override the templates for internal types.
Authentication
| Type | Value | Trigger |
|---|---|---|
| Reset Password | reset_password | A password reset is requested |
| Reset Password Confirmation | reset_password_confirmation | A password reset is completed |
| 2FA Code | two_fa | A two-factor authentication code is issued |
| 2FA Setup | two_fa_setup | Two-factor authentication is enabled on an account |
| 2FA Removed | two_fa_removed | Two-factor authentication is disabled on an account |
Admin Notifications
| Type | Value | Trigger |
|---|---|---|
| Admin: New Payment | admin_new_payment | A new payment is recorded for a service |
| Admin: Weekly Overview | admin_weekly_overview | A weekly digest of activity is sent to admins |
| Admin: Payment Problem | admin_payment_problem | A payment problem occurs on an order, subscription, or PAYG cycle |
System
| Type | Value | Trigger |
|---|---|---|
| Error | error | An internal system error requires administrator attention |
Relationships
- Services — Every SMTP setting, email setting, fallback, template, and log belongs to one service. The service's
coloris used for email branding. - Files & S3 Storage — The
header_image_file_idonEmailSettingreferences a file with categoryimage; it's served via the public download endpoint. Email and bulk email attachments also reference files this way. - Users — The
induced_byfield onEmailLogrecords which user triggered the email. Authentication emails (reset_password,two_fa, …) are always sent to TiruPay users. - Orders — Order lifecycle events fire invoice, dunning, and order notification emails.
- Trial — Starting, ending and the reminder before the end of a Trial fire the Trial email types.
- Scheduled Price Changes — Price change group processing fires the five price-change email types.
- Background Jobs — Bulk email sends run as a background job; poll it with the returned
job_id.