Complete Guide: Customizing Emails with HTML

What it is and how it works under the hood

When AdmCloud emails an invoice, a quote, a purchase order, a statement, etc., it uses a default email body. An Email Sending Format lets you replace that standard body with your own: you design the email (with your logo, colors and text) and insert the document's real data (number, customer, total, etc.).

The full cycle is:

1. You tie the format to a document type (the Object field). That type determines which data will be available: each document type has its own data "model", exactly as with printing formats.
2. You write the email body, either with the Visual editor (drag and type) or with the HTML/Razor editor (code).
3. You activate it as the default format for that document type (under Default Email Sending Formats).
4. When the document is sent, AdmCloud loads the real document, builds its data model, compiles your format replacing each expression with the real value and uses the result as the email body.

The two editor types

When creating a format you choose between two editors, and this decision determines what you can do and how the format is used:

Language supported by HTML formats

HTML-type formats are written in HTML for the structure and styling, combined with Razor (the ASP.NET view syntax, based on C#) to insert data and apply logic. You can use:

• Any HTML and CSS: tables, images, inline styles or a <style> tag, colors, fonts, etc. (aim for email-client-friendly HTML).
• Data expressions with @Model.Property (for example @Model.Relationship.Name).
• Conditionals with @if (...) { ... }.
• Loops with @foreach (var line in Model.Header.Items) { ... }.
• Value formatting with .NET methods, for example @Model.Header.DocDate.ToString("dd/MM/yyyy") or @Model.Header.TotalAmount.ToString("#,##0.00").

How to create a format, step by step

1. Go to Email Sending Formats and use the New menu. You can pick Empty Email (Visual Editor), Empty Email (HTML Editor), or start from a ready-made sample format for a specific document (the list only shows the documents enabled in your plan).
2. In Name, type a unique, descriptive name. Keep in mind the Name also acts as the suggested subject: when the format is loaded in the send window, its Name is placed in the email's Subject field. So use a name that works as a subject (for example, "Your invoice from [Company]").
3. In Object, select the document type it applies to. It defines which variables you'll have available.
4. Write the body in the matching tab: Body (Visual editor) or HTML Body (HTML editor). Lean on the sample template and on the Data Dictionary.
5. Click Save.
6. Activate it under Default Email Sending Formats for the matching document type. Until you assign it there, the saved format does not change the body of the emails.

How it is configured

The Model variables: how they work

The Model object represents the email's document. You access its data with @Model. followed by the property name, chaining with dots: @Model.Relationship.Name (the customer), @Model.CompanyInfo.CompanyName (your company), @Model.Header.DocID (the document number). It's the same data model the printing formats use, with a few email-specific variables:

Sample HTML format

This is a simple email body for sending a credit invoice. It shows the logo (or the company name), a greeting with the user's custom message, and the receipt data:

<div style="font-family:Arial,sans-serif; color:#333;">
    @if (Model.Logo != null)
    {
        <img src="@Model.Logo.URI" alt="Logo" style="max-height:60px;" />
    }
    else
    {
        <h2>@Model.CompanyInfo.CompanyName</h2>
    }

    <p>Dear @Model.Relationship.Name,</p>

    @if (!string.IsNullOrEmpty(Model.Message))
    {
        <p>@Model.Message</p>
    }

    <p>
        Please find attached invoice <strong>@Model.Header.DocID</strong>,
        dated @Model.Header.DocDate.ToString("dd/MM/yyyy"),
        for a total of @Model.Header.TotalAmount.ToString("#,##0.00").
    </p>

    @if (!string.IsNullOrEmpty(Model.CreditCardPaymentLink))
    {
        <p><a href="@Model.CreditCardPaymentLink">Pay online</a></p>
    }

    <p>Best regards,<br />@Model.CompanyInfo.CompanyName</p>
</div>

Where to look up the available variables

Email Sending Formats do not have their own data dictionary or preview; they share the data model with printing formats, so you look up the variables there:

• Open the same document type in HTML Printing Formats and use its Data Dictionary tab to see the name and type of each property.
• Or check the HTML Variables for Printing Formats screen (address /PFDocumentation), which documents, document by document, each field and its type.
• Also remember the email-specific variables listed above (Model.Message, Model.Host, Model.CreditCardPaymentLink, Model.Logo).

How to test the result

Unlike printing formats, the Email Sending Formats screen has no live preview. The recommended way to test a format is:

1. Save the format.
2. Go to a real document of that type and email it, manually choosing your format in the Composing and Sending Emails window (ideally to your own address).
3. Review the received email and adjust the format if needed, before assigning it as the default.

Activating the format and other options

• Activate it per document: assign it under Default Email Sending Formats, which has a slot for each document type (credit invoice, cash invoice, notes, quote, order, purchase order, statement, payment voucher, service requests, time off, etc.).
• Status-change notifications: a format can be attached to the email notification of a document status change (for example, in service requests).
• Plugins: a format can be bundled into a published Plugin.
• Access control by Owner, with the option to restrict editing and viewing of the code to that person only.
• Transfer to another company you administer (requires the Enterprise edition with the "Create Plugins" feature).

Tips and common mistakes