> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dmly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate client letters

> Build a reusable letter template with merge tokens and generate a branded, personalized PDF letter for one contact.

A client letter is a branded PDF built from a reusable template: a membership confirmation, a welcome letter, anything you'd otherwise write by hand. You write the template once with merge tokens for the contact's name, their custom fields and a reference number, then generate it for one contact at a time. DMLY fills in the real values, stores the result privately on that contact, and lets you download it or share it on WhatsApp.

## Where letters live

<Columns cols={2}>
  <Card title="Client letters (templates)" icon="pen-to-square">
    Select **Client letters** from the header of **Contacts** to reach the templates page. Build, edit and delete templates here.
  </Card>

  <Card title="A contact's own letters" icon="address-book">
    Open any contact and select their **Files & letters** tab, where the **Client letters** card sits next to their documents. Generate a letter for that person, and see, download or share everything already generated for them.
  </Card>
</Columns>

There's no separate template picker anywhere else; a template only becomes a letter when you generate it for a specific contact.

## Build a template with merge tokens

<Steps>
  <Step title="Open Client letters">
    Go to **Contacts** and select **Client letters** in the header.
  </Step>

  <Step title="Start a template">
    Select **New template**. This needs the **Manage letter templates** permission. See [Who can do what](#who-can-do-what) below.
  </Step>

  <Step title="Name it and write the body">
    Give it a **Template name**, then write the **Letter body** in the rich-text editor.
  </Step>

  <Step title="Insert merge tokens">
    Select any chip under **Merge variables** to add that token. Each one is appended to the end of the body, not inserted at your cursor, so add your tokens first, then arrange the wording around them.
  </Step>

  <Step title="Save">
    Toggle **Active** on (it's on by default) and select **Save**. Only active templates can be picked when generating a letter; turn a template off to retire it without deleting it.
  </Step>
</Steps>

The available tokens:

| Token                   | Fills in with                                             |
| ----------------------- | --------------------------------------------------------- |
| `{{first_name}}`        | The contact's first name                                  |
| `{{last_name}}`         | Everything after the first word of their name             |
| `{{name}}`              | Their full name                                           |
| `{{email}}`             | Their email address                                       |
| `{{phone}}`             | Their phone number                                        |
| `{{business_name}}`     | Your workspace's name                                     |
| `{{credit.balance}}`    | Their live credit balance                                 |
| `{{loyalty.points}}`    | Their live loyalty points balance                         |
| `{{custom.field_name}}` | One of their [custom fields](/contacts/custom-fields)     |
| `{{letter.number}}`     | The letter's own reference number, assigned at generation |
| `{{letter.date}}`       | The date the letter was generated                         |

<Note>
  Selecting **Custom field** inserts the literal `{{custom.field_name}}`; you have to edit `field_name` to match a field you defined under [Custom fields](/contacts/custom-fields) exactly, including capitalisation. Nothing checks the name for you: a typo resolves to an empty string in the finished letter, with no warning.
</Note>

## Generate a letter for a contact

<Steps>
  <Step title="Open the contact">
    Go to their profile and find the **Client letters** card.
  </Step>

  <Step title="Select Generate letter">
    This needs the **Generate & share client letters** permission. The button is disabled if you have no active templates yet.
  </Step>

  <Step title="Pick a template">
    Only active templates appear in the list.
  </Step>

  <Step title="Optionally set a title">
    Leave **Title** blank and DMLY uses the template's name.
  </Step>

  <Step title="Select Generate letter">
    DMLY substitutes every token with this contact's real data, assigns the letter a sequential reference (`LTR-0001`, `LTR-0002`, …, shared across the whole workspace), and renders it as a PDF.
  </Step>
</Steps>

The PDF carries your [business details](/account/business-details) in a branded header (logo, name, address and contact details) with the word "LETTER" and the reference number opposite, the generation date, the title, the letter body, and a QR code at the foot that anyone can scan to verify and reopen the same PDF online.

<Note>
  `{{phone}}` and `{{email}}` always resolve to the contact's real, unmasked values in a generated letter, even for a teammate whose own view of the contact is normally masked under [Roles and permissions](/account/roles-and-permissions). It's the client's own document, addressed to them, so there's nothing to hide it from.
</Note>

Once generated, a letter is a fixed snapshot. Editing the template afterwards doesn't touch letters you've already generated from it; generate again to pick up a template change.

## Download or share it

Every letter in the **Client letters** card has a download link and, if you can generate letters, a WhatsApp icon:

* **Download** streams the PDF to you directly; this needs no special permission beyond being able to open the contact at all.
* **Share on WhatsApp** sends the client a message carrying a secure link to the same PDF, using DMLY's approved `dmly_letter_link` template outside their 24-hour window, or a plain-text message with the link inside it. If their window is open, DMLY follows up immediately with the PDF itself as a WhatsApp document. A contact with no WhatsApp identity or number simply can't be reached this way.

<Tip>
  The link in that message is a secure, signed URL; the client opens it straight in their browser, no DMLY login required. It's the same pattern DMLY uses for invoice pay links.
</Tip>

## Its relationship to Documents

Every generated letter is also filed as a private document on that contact. See [Documents](/contacts/documents). The **Client letters** card is the friendlier view: a title, its reference number, whether it's been shared, and a one-click WhatsApp share button. The **Documents** card lists it too, alongside anything else on file for that contact, but without those letter-specific extras.

<Warning>
  There's no dedicated way to delete a single letter. Deleting its file from the **Documents** card removes the PDF but leaves the letter listed in the **Client letters** card with a download link that no longer works. Deleting the whole contact removes its letters cleanly.
</Warning>

## Who can do what

| Permission                          | Lets a teammate                                                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Any access to the Contacts module   | View the **Client letters** page and card, and download an existing letter                                          |
| **Manage letter templates**         | Create, edit and delete templates. Admin-only by default; a custom role can grant it to a Member.                   |
| **Generate & share client letters** | Generate a new letter for a contact and share it on WhatsApp. Included in the default Member role; a Viewer cannot. |

See [Roles and permissions](/account/roles-and-permissions) for how base roles and custom roles work.

<Accordion title="Share on WhatsApp doesn't seem to have sent anything">
  Selecting **Share on WhatsApp** always attempts a send; it isn't gated by the **Client & staff messages** toggles under [Notification settings](/account/notifications). What it does depend on:

  * The client is reachable on WhatsApp at all (a phone number or an existing WhatsApp identity).
  * Either `dmly_letter_link` is approved by Meta, or the client messaged you within the last 24 hours so a freeform message still gets through. See [Message templates](/broadcasts/message-templates).

  Only when both of those fail does the share silently do nothing.
</Accordion>

<Accordion title="Generate letter is greyed out">
  You need at least one active template. Check the **Client letters** templates page: a template that's toggled off (marked **Inactive**) won't appear in a contact's template picker even though it still exists.
</Accordion>

<Columns cols={2}>
  <Card title="Documents" icon="folder" href="/contacts/documents">
    Every file on a contact: uploads and generated letters alike.
  </Card>

  <Card title="Client profile" icon="user-tie" href="/contacts/client-profile">
    Everything else on a contact's profile page.
  </Card>

  <Card title="Custom fields" icon="list-check" href="/contacts/custom-fields">
    Define the fields a `{{custom.field_name}}` token can pull from.
  </Card>

  <Card title="Roles and permissions" icon="shield-halved" href="/account/roles-and-permissions">
    Who can manage templates versus who can generate and share.
  </Card>
</Columns>