Skip to main content

Email layouts

The email layout is the HTML envelope wrapping every collection message sent by email: a header with your brand, a footer with your details, and in the middle the content of the step's template. The template says what the message says; the layout says how it dresses.

The placeholders​

A layout is a full HTML document with two substitution points:

  • {{content}} (required): where the template body goes. A layout without this placeholder is rejected at creation (MISSING_CONTENT_PLACEHOLDER) — without it, the email would go out without the message.
  • {{subject}} (optional): the message subject, useful in internal HTML titles.

The cascade: branch → company → organization​

At send time, the system resolves which layout to use from most specific to most general:

  1. The branch layout (business unit) of the charge, if it has one;
  2. otherwise, the company layout;
  3. otherwise, the organization's default layout (the one marked as default);
  4. otherwise, the product's built-in layout: a neutral responsive HTML (600px white card, footer "Mensagem enviada automaticamente pelo sistema de cobrança").

This lets a group with multiple brands send each charge with the right company's identity, without duplicating rules or templates. The company/branch → layout association is done in the organizational structure.

Inactive or deleted layouts are never used: the cascade simply moves on to the next level.

Managing layouts​

Management is done through the API (/api/v1/email-layouts), with the email_layouts.* permissions from the catalog:

  • List (GET) returns the organization's layouts, how many companies use each one and also the HTML of the built-in layout, which serves as a starting point for yours.
  • Create (POST) requires name (2 to 80 characters) and htmlBody (minimum 20 characters, containing {{content}}). Setting isDefault: true automatically unsets the previous default: there is only one default per organization.

Each creation is recorded in the audit trail.

Best practices​

  • Start by copying the built-in layout and swap colors, logo and footer: it is already responsive and tested across email clients.
  • Use HTML tables and inline CSS: email is not a browser, and the most popular email clients ignore external stylesheets.
  • Include the creditor's legal name and contact details in the footer: beyond good practice, it reduces spam flagging and supports the requirement of clearly identifying the collector.
  • Test the cascade: send a test charge through a branch with its own layout and another through a company without one, and confirm each goes out wearing the right clothes.