![Ringle](assets/ringle-logo.png)

# Message templates and sending domains

## Purpose
The Message Templates page owns everything the assistant sends over email and SMS: the templates themselves, a delivery log of what actually went out, the custom email sending domains, and the branded short-link domains used in outbound messages.

## Prerequisites
- A tenant role with tenant settings permission; members without it do not see Message Templates in the sidebar.
- Domain changes affect live deliverability. This guide only opens the add-domain dialogs and cancels them.

## Steps

### Step 1

![messaging-templates-and-domains, step-01](screenshots/messaging-templates-and-domains/step-01.png)

**Action:** Click Message Templates under Voice & Messaging in the sidebar.

**What you should see:** The page opens on the first of five tabs: Email Templates, SMS Templates, Delivery Log, Domains, and Short Link Domains. The Email Templates tab shows a table with Template Key, Name, Subject, Status, Updated, and Actions columns, plus a Create Email Template button. Each template that exists lists its key (such as `order_status_found`), name, subject line, an Active status chip, the last update time, and edit and delete icons. The demo tenant has no templates yet, so an empty state with a Create Template button appears.

### Step 2

![messaging-templates-and-domains, step-02](screenshots/messaging-templates-and-domains/step-02.png)

**Action:** Click Create Email Template (or the pencil on an existing template) to open the editor. Review it. Then click Cancel.

**What you should see:** The template editor opens. Create Email Template has a Template Key field (unique identifier), a Description, the Name and Subject fields, HTML Body and Text Body (fallback) editors, and a row of clickable variable chips: `{{customer_name}}`, `{{customer_email}}`, `{{customer_phone}}`, `{{order_id}}`, `{{order_total}}`, and `{{tenant_name}}`. Editing an existing template shows the same fields with the Template Key locked. Cancel closes the dialog without saving. See Troubleshooting for a known gap where the Edit dialog opens with empty body fields.

### Step 3

![messaging-templates-and-domains, step-03](screenshots/messaging-templates-and-domains/step-03.png)

**Action:** Switch to the SMS Templates tab.

**What you should see:** The tab shows the same table pattern for SMS (key, text, status, updated). The demo tenant has none yet, so an empty state with a Create Template button appears.

### Step 4

![messaging-templates-and-domains, step-04](screenshots/messaging-templates-and-domains/step-04.png)

**Action:** Switch to the Delivery Log tab.

**What you should see:** A read-only log of outbound messages appears, with Status and Channel filters and columns for To, Subject, Template, Channel, Status, and Sent. Each row shows the recipient, subject, template (when one was used), a channel chip, a status chip (sent, delivered, or bounced), and the send time. Pagination sits at the bottom. The demo tenant has sent nothing yet, so the tab shows "No delivery logs yet".

### Step 5

![messaging-templates-and-domains, step-05](screenshots/messaging-templates-and-domains/step-05.png)

**Action:** Switch to the Domains tab.

**What you should see:** The tab explains that registering your own email domain lets customers reach you at your address. It lists registered domains with status, verification date, and a delete action. Rows that are not yet verified also show a Verify button. The demo tenant has no domain configured, so an empty state with an Add Domain button appears.

### Step 6

*Screenshot not available (the demo tenant has no email domain to expand)*

**Action:** Click the caret at the left of a domain row to expand it.

**What you should see:** The row expands to show the DNS records to add at your domain provider: a DKIM TXT record, an MX record, and an SPF TXT record. Each record has its own status chip and a copy button for its value.

### Step 7

![messaging-templates-and-domains, step-07](screenshots/messaging-templates-and-domains/step-07.png)

**Action:** Click Add Domain. Review the dialog. Then click Cancel.

**What you should see:** The Add Custom Email Domain dialog asks for a single Domain Name (for example `support.yourdomain.com`). It recommends a subdomain if the root domain already handles email. The Add Domain button stays disabled until a name is entered. Cancel closes the dialog without adding anything.

### Step 8

*Screenshot not available (the demo tenant has no short-link domain to expand)*

**Action:** Switch to the Short Link Domains tab. Expand the domain row.

**What you should see:** This tab manages the branded domain used for the short URLs Ringle sends in SMS, chat, and email. It opens with an explanation and an Add Domain button; the demo tenant has none configured, so an empty state shows. Once a domain is added, its row expands to the single CNAME record to add (the domain pointing at Ringle's short-link host) with a copy button. While a domain is verifying, the row shows a spinner and the page re-checks automatically.

### Step 9

![messaging-templates-and-domains, step-09](screenshots/messaging-templates-and-domains/step-09.png)

**Action:** Click Add Domain on this tab. Review the dialog. Then click Cancel.

**What you should see:** The Add Short-Link Domain dialog asks for the branded domain (for example `links.acme.com`). It notes that a CNAME record follows and that the TLS certificate is provisioned automatically once the CNAME resolves. Cancel closes it without changes.

## Troubleshooting
- The template editor opens with empty HTML Body and Text Body fields even though the template clearly sends content: a known gap; the list does not carry the bodies into the dialog. Do not click Save Changes on a template you only meant to inspect, or you can clear its body. Cancel instead.
- A bounced status in the Delivery Log means the recipient's server rejected the message. Check the address, and check that your sending domain is verified on the Domains tab.
- A new email domain stays Pending: the three DNS records must all resolve. Expand the row, add each record exactly as shown, wait for DNS propagation, then click Verify.
- A short-link domain is stuck at Verifying: confirm the CNAME points at the value shown in the expanded row. The page polls every few seconds and flips to Verified on its own once the record resolves and TLS is issued.

## Notes
- Route: `/settings/messaging`, sidebar item "Message Templates" under Voice & Messaging, gated by the `tenants.settings.manage` permission.
- Source: `pages/settings/MessagingTemplatesPage.jsx`; the Domains tab renders `components/messaging/DomainManagementPanel.jsx` and the Short Link Domains tab renders `components/messaging/ShortLinkDomainPanel.jsx`.
- Email sending domains verify with three DNS records (DKIM, MX, SPF); short-link domains verify with a single CNAME.
- Captures were taken in the Demo Auto Shop tenant, which has no templates or domains configured, so the tabs show their empty states. Step 2 shows the Create Email Template dialog because there was no template to edit. Steps 6 and 8 need an existing domain to expand, so they are described but not shown. No templates were saved and no domains were added, verified, or deleted; both add dialogs were cancelled.