NirmaanOne Help
How-toReviewed 2026-09-29

Design an email template and use it in a rule

Write a reusable email (subject, designed body, plain-text version and optional generated attachments) with merge fields, preview it against a real record, and have a workflow rule send it.

Design an email template and use it in a rule

A message template holds the wording of an email once, with merge fields that fill in the buyer's name, the unit, the amount due or the booking number for each record. Workflow rules send it, and so do campaigns. This guide writes a template, checks it against a real record, and has a rule send it.

Before you start

  • You need the Create permission on Message Templates to write a template and the Edit permission on Message Templates to change one: the Administrator and the Sales Manager in the default roles. Adding the email to a rule needs the Edit permission on Workflow Rules (only the Administrator by default).
  • Decide which record the email is about (a demand, a booking, an estimate…): it decides the merge fields on offer and which rules can use the template. For a campaign, use Contact or leave the record type as "Any record".
  • To attach a generated letter (a demand letter, a receipt), its document template must be Published for the same record type under Document templates.
  • To change the wording of a system email instead ("Payment reminder", "Booking confirmation" and the others), open it from the list and edit it; its code is fixed but its wording is yours.

Steps

  1. Open the account menu > Settings > Workflows > Message templates (Message templates). The list shows every template, including six system Email templates such as "Payment reminder" (for a demand) and "Booking confirmation" (for a booking).
  2. Click New template. The New message template page opens, with the Variables reference on the right.
  3. Fill in the details:
    • Code (required): capital letters, digits and underscores, up to 50 characters and never reused (placeholder "BOOKING_CONFIRMED");
    • Name (required, up to 150 characters);
    • Channel: keep Email ("Sent through the organization's mail server; needs a subject."). It can't change later;
    • Record type: the record the email is about, for example Demand. The Variables panel then lists that record's columns and its related rows (the contact, the unit, the project);
    • Subject (required for Email): merge fields work here too, for example "Payment due for Unit {{ unit.unit_number }}".
  4. Write the Email body in the rich editor: format the text and insert merge fields from the toolbar, or copy them from the Variables panel. Then write the Plain-text version (required, up to 20 000 characters; placeholder "Dear {{ contact.first_name }},"): it is sent alongside the designed body for mail programs that show plain text, and alone when the designed body is empty.
  5. To attach a document, click Attach a generated document, pick the document template ("Choose a document template…") and the Format (PDF or Word). Up to five; the x removes one. Each time the email goes out, the document is generated for the record and attached.
  6. Under the settings card, add a Description ("Optional; shown in the list."), a Sort order ("Order in pickers") and keep Active ticked. Click Create template. You see '"<name>" created.' and the template's page opens (Message template).
  7. In the Preview panel ("Render the saved template against a record."), pick a Record (for a template without a record type, choose the Entity first) and click Preview. The panel shows the merged Subject, HTML body and Plain-text body for that record. For a template that reads a manual form's values or an event's keys, type them under Extra context (optional). Nothing is sent. Fix the wording, click Save changes ('"<name>" saved.') and preview again.
  8. Open the rule that should send the email (Rule; it must watch the same kind of record as the template). In Actions, click Add action and pick Send email. A Send email card appears at the end.
  9. In the card, fill in To (addresses or merge fields, comma separated, up to 20; usually {{ contact.email }}), choose Use a message template and pick yours under Email template ("Active Email templates from the Message templates tab."). The card notes "Attachments configured on the message template itself are added too."; add more under Attach documents if needed.
  10. Click Save changes. You see '"<rule name>" saved as version <n>.' Back on Message templates, your template's Used by column now counts the action.

What happens next

  • The rule sends the current wording. Whenever the rule fires, the template is merged for that record and sent; later edits to the template apply from the next send, without touching the rule.
  • Every send is logged on the Runs tab: the Send email step shows its result, or the error when no address could be found.
  • Campaigns can use it when its record type is Contact or "Any record": see Run an email campaign.
  • A template in use can't be deleted. Its Delete icon is greyed out with "Used by workflow actions; remove it from them first". Make it inactive instead: it stays on the actions that use it but isn't offered for new ones.
  • To switch on a ready-made rule that emails customers, review its template this way first; see Switch on a system rule.

If something goes wrong

  • "Email templates need a subject" on Subject, or a merge-field mistake reported as "<field>: <problem> (line <n>)" when you save: fix the text at that line. "The extra context is not valid JSON." or "Choose an entity to preview the template against." in the preview: correct the extra context, or pick an entity. See Template syntax error (trouble.documents.template-syntax-error).
  • "A template with this code already exists (codes are never reused).": choose another code. See Already exists (trouble.admin.already-exists).
  • "<CODE> renders a <record>; this template is for <record>" or "<CODE> is attached twice": attach only published document templates of the template's record type, once each. A document template you expect isn't offered: it isn't published, or it is for another record type.
  • "SEND_EMAIL needs a message_template_id or both subject and body" when saving the rule: pick a template, or switch to Write the email here. Your template isn't in the Email template list: it is inactive or not an Email template. See Rule cannot be saved (trouble.workflows.rule-cannot-be-saved).
  • The run's Send email step ends Errored with "no_recipients: No valid email address after rendering the recipients", or ends Success with "MAIL_SERVER is not configured; the message was logged": the record's contact has no email address, or your server has no mail set up. See Email not sent (trouble.workflows.email-not-sent) and, for mail that was only logged, Email not delivered (trouble.documents.email-not-delivered).
  • The step fails with "Template <CODE> is not published": an attached document template was retired or never published. Publish it under Settings > Documents. See Action failed (trouble.workflows.action-failed).
  • "Workflow actions use this template; change them first" when deleting: a rule still uses it. See Rule cannot be deleted (trouble.workflows.rule-cannot-be-deleted).

Related

  • Message templatesScreen

    The list of your organization's message templates: the wording that Send email actions and campaigns use, with filters and the actions to create, open or delete one.

  • New message templateScreen

    Write a message template on its own page: code, name, channel, record type, subject, the designed email body and its plain-text version, attachments, and the merge-field reference.

  • Message templateScreen

    One message template's page: change its wording, attachments and settings, and preview it filled in for a real record.

  • RuleScreen

    One automation rule's page: read or change its basics, trigger, conditions and actions, test it against a record, clone or delete it, and switch a system rule on or off.

  • New ruleScreen

    Build an automation rule on a full page: which records it watches, what starts it, which records qualify, and the ordered actions it carries out.

  • RunsScreen

    Every time a rule ran: what started it, which record it worked on, how each action went, and the panel from which an errored run is retried.

  • Document templatesScreen

    The list of your organization's document templates (demand letters, offer letters, termsheets, agreements, allotment letters, receipts, cost sheets), with filters and the actions to create, duplicate, open or delete one.

  • New campaignScreen

    Create an email campaign: name it, choose the email template, tag a project, set the reply-to address and define who receives the mail, with a live count of the audience.

  • Build and switch on a custom ruleHow-to

    Build your own automation rule on the rule editor (what it watches, what starts it, which records qualify and what it does), save it switched off, try it on a real record with a dry run, then switch it on and check its runs.

  • Switch on a system ruleHow-to

    Switch on one of the ready-made system rules that ship switched off, such as emailing the demand letter when a demand is issued: publish the document template it uses, review and preview its email template, then press Switch on and check its runs.

  • Run an email campaignHow-to

    Email a launch, an offer or a reminder to a chosen audience of contacts and leads: pick an Email template, define and count the audience, build the recipient list, preview and test the merged mail, then send it now or schedule it, and follow the delivery log.

  • Put a starter document template into useHow-to

    Review one of the six starter templates that come as drafts, preview it against a real record, publish it, and switch on the system workflow rule that sends it automatically.

  • Message templatesConcept

    The reusable wording of the emails that workflow rules, record-page buttons and campaigns send: a code, a channel, a subject and body with merge fields, an optional rich HTML body and up to five generated-document attachments, rendered against the record that triggered it.

  • Merge fields and filtersConcept

    Merge fields are the double-brace placeholders in document and message templates ({{ entity.demand_no }}, {{ contact.name }}) that are replaced with the record's values when a document or message is rendered; filters such as inr, words and date format the value, and Repeat row / Show when add tables and conditional blocks.

  • Template will not save, publish or render: a tag, expression or the HTML is wrongTroubleshooting

    A document template, message template or rule action that carries a broken merge tag is refused when saved or published, names the field and the line; a template that parses but fails while filling in a record, or whose HTML the PDF or Word engine cannot lay out, fails at preview, generation or sending; the editor's own dialogs and fields have their own checks.

  • Email action or document email did not go out: no valid recipient, or the message is incompleteTroubleshooting

    A Send email action fails when its To line renders no valid address (usually because the contact has no email), a rule with Send email cannot be saved without a message template or a subject and body, a document email needs at least one valid address and is refused for a void document, and an Email message template needs a subject.

  • Email shows as logged or refused: the mail server is not configured or rejected the messageTroubleshooting

    Outgoing mail is sent through a mail server set up for the installation, not inside the app; while none is configured every email (document, campaign, workflow, invitation, verification) is only logged and reported as not delivered, and when the server refuses a message the recipient is marked failed; the person who runs the installation configures mail, then you resend.

  • A run's action errored: webhook refused, empty role, empty reason, unpublished template or the chain ran too deepTroubleshooting

    A workflow run stops as Errored when one of its actions fails: the webhook address is internal or the other system refused the call, the role to assign to has no active members, a cancellation or lost reason came out blank, or the document template is not published; a run is Blocked when a chain of rules emitting events runs deeper than the engine allows.

  • Workflow rule, event type or message template cannot be deleted: runs, rules or actions use itTroubleshooting

    A workflow rule that has run is kept for its history and a system rule is never deleted or edited; switch them off instead. A custom event type that rules listen to, a message template that workflow actions or campaigns use, cannot be deleted either; deactivate it, or change what uses it first.

  • Workflow rule will not save: a trigger, schedule, condition or action is incomplete or not allowedTroubleshooting

    Create rule or Save changes is refused when the trigger is missing its event type, schedule or input form, when a condition names a field the record doesn't have, when an action is switched off on this server or is set up in a way the engine doesn't allow, or when the rule has nothing to do.

  • "Already exists" or "listed twice": the name, code, number or line must be uniqueTroubleshooting

    Names, codes and numbers are unique within their scope (the organization, a project, a tower, a set of books) so that records can be told apart, and a line can appear once on a plan, offer or account; rename, reuse the existing record, or remove the duplicate line.