Emails

Your site sends emails: a password reset link, a confirmation that someone's address is theirs and, with the matching features, an order confirmation or a notice that a form was filled in. Each one is a page that you edit in the same editor as any other page, using a small set of email blocks.

After this chapter you can change the wording and look of an email, preview it, send yourself a test, change the frame around every email, and choose who the emails come from and which service sends them.

Edit an email

  1. Open Content → Emails. The list names each email, says when it is sent and shows whether it goes to a customer or to staff.
  2. Click the email you want. The editor opens.
  3. Click an empty part of the preview to change the Subject and the Preview text, which is the line a mail app shows next to the subject. The preview text is not part of the email itself.
  4. Edit the blocks. The email blocks are Heading, Text, Button, Image, Divider and Spacer. Other blocks fill themselves in from what the email is about: Order items and Order addresses in order emails, Submitted fields in the form notice, and others for the other features. Only the blocks that make sense for that email are offered.
  5. Press Save draft, then Preview to see the real, rendered email with sample data.
  6. Press Send test to email the saved draft to yourself, also with sample data.
  7. Press Publish. The next email the site sends uses the new version.

The emails a site has depend on its features. Password reset and the two address confirmations are always there. A site with the shop also has the order emails, one with forms has the form notice, and the other features add their own. You cannot add or delete an email, because the site keeps the full set.

Use placeholders for what changes

A placeholder is a name in curly braces that the site replaces with the real value when it sends the email. Type {orderNumber} in a subject such as “Your order {orderNumber}” and the customer sees their own number. {siteName} and {siteUrl} work in every email.

Press Placeholders in the editor to see the list for the email you are editing, with a note on each. Type them with the braces, in the subject, the preview text, headings, text and links. Headings and buttons show sample values in the editor, and text shows the placeholder as you typed it. Preview and Send test show the real thing. A placeholder the email does not know is left as you typed it.

Change the frame around every email

Emails have layouts of their own. A layout is the frame around an email: a brand line above it and a footer below, with a Page content block where the email's own blocks go. The layout named email wraps every email unless an email picks another.

  1. Open Content → Layouts and open email.
  2. Edit it like any page. Keep the Page content block in place.
  3. Press Publish. Every email that uses it changes.

To make another one, press New layout and choose Email layout as its Type. An email picks a layout in its own Layout field, which is with the Subject when you click an empty part of its preview. Site layouts, for pages, are described in Pages and blocks.

Choose who sends the emails

Admins set the sender under Settings → Email.

  1. Under Sender, type a From name, which shows next to the address in the inbox, and a From address. Left blank, the site sends from a default address. Your email service must be allowed to send as the address you choose.
  2. Add a Reply-to address if replies should go somewhere else. Form notices reply to the visitor who filled the form in.
  3. On a site with the shop, New order notifications lists the staff addresses that receive the “New order (staff)” email, one address per line. Each form has its own notification addresses.
  4. Press Save settings.
  5. Type your own address under Send a test email to and press Send test. It uses the saved settings.

Choose the service that sends them

The service that actually delivers email is an adapter, set in site.config.ts. A new site uses consoleEmail(). It sends nothing. It prints a summary of each email in the terminal and writes the full email to the .cms/mail folder, which is how you see emails while you build.

To send real email you need an account with a service. The cms works with any that offers SMTP, using smtp(), and with Amazon SES, using ses(). The example below uses SMTP. Passwords and keys never go in the database or in site.config.ts. They stay in .env, and Settings → Email shows whether each one is set.

  1. Install the SMTP adapter:
pnpm add @jamiemcconnell/cms-email-smtp
  1. Import it in site.config.ts and use it as the site's email adapter in place of consoleEmail():
site.config.ts
import { smtp } from '@jamiemcconnell/cms-email-smtp';

// Inside defineConfig({ ... }), instead of consoleEmail():
email: smtp(),
  1. Add your service's connection address to .env. Replace the user name, password and host with the ones your service gives you:
.env
SMTP_URL=smtp://username:password@smtp.example.com:587
  1. Restart the site, open Settings → Email and send yourself a test.

Instead of one address, SMTP_USER and SMTP_PASSWORD can hold the credentials, with the host and port typed in Settings → Email. Amazon SES reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION from .env. To choose between services in the admin, list several adapters in email. The Send with list under Provider then offers each one. Going live covers the other adapters a live site needs.