Skip to content

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:

  1. 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.
  2. Template lookup — TiruPay searches for the best-matching EmailTemplate for the type, locale, and service (see Template Resolution).
  3. Placeholder substitution — %placeholder% tokens in the template body and footer are replaced with real values (e.g. %user_name% → "Jane Doe").
  4. HTML rendering — The substituted body is wrapped in a styled layout that applies your service's branding (header image, brand color, footer).
  5. SMTP dispatch — The final HTML email is sent via the resolved SMTP configuration.
  6. Logging — Every delivery attempt is logged in an EmailLog record, 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.

FieldTypeDescription
idstringUnique identifier
namestringHuman-readable label (internal only)
email_fromstringThe sender address used in the From header
serverstringSMTP server hostname
portintegerSMTP server port (e.g. 587, 465)
usernamestringSMTP authentication username
passwordstringSMTP authentication password
use_tlsbooleanWhether to use TLS
service_idstringThe service this setting belongs to
created_atdatetimeWhen this setting was created
updated_atdatetimeWhen 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.

FieldTypeDescription
header_image_file_idstring | nullFile ID of an image shown at the top of every outgoing email
footer_default_textstring | nullDefault footer text appended to every email (can be overridden per template)
default_smtp_email_setting_idstring | nullDefault 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 ​

FieldTypeDescription
idstringUnique identifier
typeenumThe EmailType this template is for (see Email Types)
localestringLocale code (e.g. en, de)
subjectstringEmail subject line
contentstringHTML body fragment — the inner content, without the surrounding chrome
footer_overwritestring | nullWhen set, replaces the EmailSetting.footer_default_text for this template
smtp_email_setting_idstring | nullPins this template to a specific SMTP setting (overrides the service default)
is_globalbooleantrue for TiruPay-provided default templates; false for service-specific templates
service_idstring | nullnull for global templates; the owning service ID for service-specific templates
created_atdatetimeWhen this template was created
updated_atdatetimeWhen 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:

  1. Service-specific template for the requested type + locale + service_id
  2. Service fallback — the template referenced in the service's EmailFallback record for this type (if one is configured)
  3. Global template for the requested type + locale
  4. 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:

PlaceholderDescription
%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's color
  • The email body (content after placeholder substitution), injected verbatim
  • A footer with the footer_default_text (or the template's footer_overwrite if 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.

FieldTypeDescription
service_idstringThe service this fallback belongs to (part of primary key)
typeenumThe EmailType this fallback covers (part of primary key)
email_template_idstring | nullThe 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:

SegmentValueRequired fieldRecipients
All Customersall_customers—Every customer in scope
Article Buyersarticle_buyersarticle_idCustomers with a paid order for this article
Article Extension Buyersarticle_extension_buyersarticle_extension_idCustomers with a paid order for this article extension
PAYG Plan Buyerspayg_plan_buyerspayg_plan_idCustomers with a balance on this PAYG plan
Active Subscribersactive_subscribersarticle_idCustomers 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 ​

  1. Preview the recipient count — POST /admin/email/bulk/recipients/count returns how many customers the segment currently resolves to, without sending anything.
  2. Export recipients as CSV, if you'd rather send through an external tool — POST /admin/email/bulk/recipients/export.
  3. Send — POST /admin/email/bulk/send enqueues the send as a background job and returns a job_id immediately (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.

FieldDescription
idUnique identifier
email_template_idThe template that produced this email, or null for an untemplated send (e.g. bulk email)
subjectSubject line of the sent email
contentRaw template content at send time (before placeholder substitution and HTML wrapping)
footerRaw footer text at send time (before placeholder substitution)
errortrue if delivery failed
error_messageError details if error is true
induced_byID of the user who triggered the action that caused the email
smtp_email_setting_idWhich SMTP setting was used
service_idThe service the email was sent for
created_atWhen the delivery was attempted
recipientsThe recipient addresses of the email
attachmentsThe 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.

FieldTypeDescription
file_idstring | nullThe attached file, or null if the attachment wasn't sourced from an uploaded file
overwrite_filenamestring | nullFilename shown to the recipient, if different from the file's own name
created_atdatetimeWhen the attachment was recorded
fileobjectThe 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 ​

TypeValueTrigger
InvoiceinvoiceAn invoice is issued for an order
DunningdunningA dunning reminder is sent for an unpaid invoice
Credit Notecredit_noteA credit note is issued

Payments ​

TypeValueTrigger
Payment Method Failurepayment_method_failureA payment method charge fails
Mandate Failuremandate_failureA SEPA/direct debit mandate fails
Mandate Payment Pendingmandate_payment_pendingA mandate payment is pending clearance
Refund Succeededrefund_succeededA refund is processed successfully
Refund to Credit Balancerefund_to_credit_balanceA refund is credited to the customer's Credit Balance instead of the original payment method

One-time Orders ​

TypeValueTrigger
Order Payment Reminderorder_reminderAn unpaid order still needs payment
Order Paidorder_paidAn order is successfully paid
Order Refundedorder_refundedAn order is fully refunded
Order Revokedorder_revokedAn order is revoked/cancelled

Subscriptions ​

TypeValueTrigger
Subscription Activatedsubscription_activatedA subscription is created and active
Free Tier Activatedfree_tier_activatedA Free Tier subscription starts
Renewal Remindersubscription_renewal_reminderAn upcoming renewal is approaching
Cancellation Noticesubscription_cancellation_noticeA subscription is cancelled
Paused Noticesubscription_paused_noticeA subscription is paused
Reactivated Noticesubscription_reactivated_noticeA paused subscription is reactivated
Upgrade Noticesubscription_upgrade_noticeA subscription is upgraded to a higher tier
Downgrade Noticesubscription_downgrade_noticeA subscription is downgraded to a lower tier
Termination Noticesubscription_termination_noticeA subscription reaches its end and terminates
Coupon Appliedcoupon_applied_to_subscriptionA subscription's recurring coupon is switched directly, taking effect at the next renewal
Coupon Removedcoupon_removed_from_subscriptionA 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.

TypeValueTrigger
Trial Started (then paid plan)trial_started_convertA Trial started that continues as a paid plan
Trial Started (then free plan)trial_started_fallbackA Trial started that moves to the Free Tier
Trial Started (then ends)trial_started_expireA Trial started that simply ends
Trial Ending Soon (then paid plan)trial_ending_soon_convertReminder before the end of a Trial that continues as a paid plan
Trial Ending Soon (then free plan)trial_ending_soon_fallbackReminder before the end of a Trial that moves to the Free Tier
Trial Ending Soon (then ends)trial_ending_soon_expireReminder before the end of a Trial that simply ends
Trial Ended (now paid plan)trial_ended_convertedA Trial ended and the plan continues as a paid plan
Trial Ended (now free plan)trial_ended_fallbackA Trial ended and the customer is on the Free Tier
Trial Ended (access ended)trial_ended_expiredA 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 ​

TypeValueTrigger
Consent Requiredprice_change_consent_requiredCustomer consent is requested for a scheduled price change
Consent Warningprice_change_consent_warningA reminder that the consent deadline is approaching (implies possible cancellation)
Consent Confirmationprice_change_consent_confirmationCustomer's acceptance of the price change is confirmed
No-Consent Confirmationprice_change_no_consent_confirmationCustomer's rejection is acknowledged (subscription may be cancelled)
No-Change Noticeprice_change_no_changeInforms 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) ​

TypeValueTrigger
PAYG Setup Confirmationpayg_setup_confirmationA PAYG agreement is set up
PAYG Usage Alertpayg_usage_alertUsage reaches the configured limit
PAYG Billing Noticepayg_billing_noticeA PAYG period is billed
PAYG Below Thresholdpayg_below_threshold_noticeUsage occurred but stayed below the billing threshold — no charge
PAYG Problempayg_problemA PAYG billing cycle fails

TiruPay-internal types ​

These types are managed entirely by TiruPay. Services cannot override the templates for internal types.

Authentication ​

TypeValueTrigger
Reset Passwordreset_passwordA password reset is requested
Reset Password Confirmationreset_password_confirmationA password reset is completed
2FA Codetwo_faA two-factor authentication code is issued
2FA Setuptwo_fa_setupTwo-factor authentication is enabled on an account
2FA Removedtwo_fa_removedTwo-factor authentication is disabled on an account

Admin Notifications ​

TypeValueTrigger
Admin: New Paymentadmin_new_paymentA new payment is recorded for a service
Admin: Weekly Overviewadmin_weekly_overviewA weekly digest of activity is sent to admins
Admin: Payment Problemadmin_payment_problemA payment problem occurs on an order, subscription, or PAYG cycle

System ​

TypeValueTrigger
ErrorerrorAn internal system error requires administrator attention

Relationships ​

  • Services — Every SMTP setting, email setting, fallback, template, and log belongs to one service. The service's color is used for email branding.
  • Files & S3 Storage — The header_image_file_id on EmailSetting references a file with category image; it's served via the public download endpoint. Email and bulk email attachments also reference files this way.
  • Users — The induced_by field on EmailLog records 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.