Your module's email and document

Every customer email a Light shop sends, and every order confirmation, invoice, credit memo, packing slip and return slip it prints, wears one look: the store's logo, the accent colour the owner picked, a footer with the company details from Business details, and one of three formats (Clean, Bold, Letter). Mrx_Documents holds that brand kit, and the owner changes it on Settings > Emails & documents. Your module writes only the body of its email or PDF; Light draws the rest. Emails come first, then your module's document, a client format and what an agency can change.

When to use itCopy Anchor Link

• Your module sends an email to a customer: a confirmation, a status change, a message. Write the body only, in the shop's own warm voice (Built for Light, rule 6).
• Your module's email has a visual need the classes below don't cover: a small {{inlinecss}} file of your own, with the two tokens for the accent.
• Your module prints a document for the shop or its customer: a delivery note, a voucher, a certificate. Add a type to the documents pool and write its body.
• Your module has its own product type, and its items need more than a name, a SKU and a quantity on an invoice: an item line in the item_lines pool.
• Your module adds something to a document it doesn't own, such as the pickup point on the packing slip: a section in the document_sections pool.
• Your module knows where products are stored: bin locations for the picklist in the pick_locations pool.
• An agency builds one look for many shops: a format in the formats pool. The colour, the logo and the footer stay the owner's settings.
• An agency changes one shop's look: start on the settings screen and go further only when it falls short (light to heavy).

How a mail gets its lookCopy Anchor Link

A body starts with the stock header include and ends with the stock footer include. Light maps both to its own shell and fills in the brand kit of the mail's store:

• MapShellIds, a before plugin on AbstractTemplate::loadDefault(), loads mrx_documents_email_header and mrx_documents_email_footer where the stock ids design_email_header_template and design_email_footer_template are asked for.
• The header puts email.css (dark mode, phones, client fixes) in a <style> and inlines email-inline.css and the format's own file. Each file passes through Css\Processor::process(), where SwapCssTokens fills the tokens with the brand kit of the store the mail renders for.
• AddDocumentVariables adds mrx_format, the logo, the footer text, the company lines and mrx_accent, so the wrapper table carries the class mrx-f-<format>.
• ApplyEmailTexts puts the subject, opening text and button text the owner saved in Settings > Customer emails into a body of the emails pool as it loads (step 5).
• AddPlainTextPart adds a plain-text part when the mail is sent (A plain-text part).
• A header the owner saved in Marketing > Email Templates still wins, and the doctor says so (email_shell_config). "Magento classic" (Stores > Configuration > Sales > Emails and documents (Light) > Advanced) switches the whole look off.

Your module's emailCopy Anchor Link

<template id="mrx_returns_email_customer_new" label="Return request received (customer, Light)" file="customer_new.html" type="html" module="Mrx_Returns" area="frontend"/>

{{template config_path="design/email/header_template"}}

<table>
    <tr class="email-intro">
        <td>
            <p class="greeting">{{trans "%name," name=$customer_name}}</p>

{{template config_path="design/email/footer_template"}}

<!--mrx:button-->
<table class="button" role="presentation" width="100%" border="0" cellspacing="0" cellpadding="0">
    <tr>
        <td>
            <table class="inner-wrapper" role="presentation" border="0" cellspacing="0" cellpadding="0" align="left">
                <tr>
                    <td align="center">
                        <!--[if mso]><v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="{{var mrx_order_url}}" style="height:44px;v-text-anchor:middle;width:220px;" arcsize="12%" stroke="f" fillcolor="{{var mrx_accent}}"><w:anchorlock/><center style="color:#ffffff;font-family:Arial,sans-serif;font-size:15px;font-weight:bold;">{{trans "View your order"}}</center></v:roundrect><![endif]-->
                        <!--[if !mso]><!--><a href="{{var mrx_order_url}}" target="_blank">{{trans "View your order"}}</a><!--<![endif]-->
                    </td>
                </tr>
            </table>
        </td>
    </tr>
</table>
<!--/mrx:button-->

<table class="email-items mrx-return-items" cellpadding="0" cellspacing="0">
    <thead>
        <tr>
            <th></th>
            <th>{{trans "Product"}}</th>
            <th>{{trans "SKU"}}</th>
            <th class="item-qty">{{trans "Qty"}}</th>

<item name="button" xsi:type="boolean">true</item>
<item name="group" xsi:type="string">orders</item>

<type name="Mrx\Settings\Model\CustomerEmails\EmailPreview">
    <arguments>
        <argument name="providers" xsi:type="array">
            <item name="return_new" xsi:type="object">Mrx\Returns\Model\Backend\Rma\ReturnPreview\Proxy</item>
            <item name="return_status" xsi:type="object">Mrx\Returns\Model\Backend\Rma\ReturnPreview\Proxy</item>
        </argument>
    </arguments>
</type>

Light's order, invoice and shipment mailsCopy Anchor Link

Light writes its own bodies for the three mails customers read most, each with a guest version, and points Magento's config paths at them:

• They keep Magento's variables, payment_html and the email-intro row, so a payment module's link in payment_html and the variables your observer adds still reach the mail.
• The order and payment mails have a "View your order" button; a guest's leads to the guest order form. The shipping mail has "Track your parcel" when the shipment has a tracking number, and no tracking block when it has none.
• The item rows show a product picture. Light sets its own item template on the default renderer of sales_email_order_renderers and its invoice, shipment and credit memo twins; a renderer of your own product type keeps its template, and its rows line up without a picture.
• "Magento classic" sends Magento's own bodies again. A body the owner picked in Marketing > Email Templates still wins, because a numeric config value never loads a file.

The variables of the sales bodiesCopy Anchor Link

AddSalesEmailVariables observes email_order_set_template_vars_before and the invoice, shipment and credit memo events (Events) and adds these variables, which your own body for a sales mail can read too:

A plain-text partCopy Anchor Link

Every mail the shop sends, yours included, goes out with a plain-text part next to its HTML. AddPlainTextPart, a before plugin on Magento\Framework\Mail\TransportInterface::sendMessage(), makes it from the HTML when the message has none: headings and paragraphs on their own lines, a link as text (url), an image as its alt text. A message that already has a text part keeps its own, and attachments stay where they are. So give an image an alt and a link text that reads without the picture.

Copies of sent mailsCopy Anchor Link

Light keeps an exact copy of every customer mail about an order. On the order page, the timeline line of that mail gets a View email button, which opens the mail as the customer got it: the subject, the To and Cc addresses, the send time, the names of the attachments and the HTML, in a frame without scripts.

Which mails get a copyCopy Anchor Link

Your module's mail gets a copy when both of these hold:

• Its template vars name the order: order (the order object), order_id, or rma (an object with getOrderId()).
• One of its To addresses is the order's customer email or the email of the customer's account. Case and spaces don't count. Mails to staff, and the separate "copy to" mails of the sales senders, go to other addresses and get no copy.

Light's contact mail passes the order's id next to its number for this:

'order_increment_id' => $order !== null ? (string)$order->getIncrementId() : '',
'order_id' => $order !== null ? (int)$order->getEntityId() : 0,

Two plugins take the copy while the mail is sent: one on Magento\Framework\Mail\Template\TransportBuilder notes the template id and the vars, one after TransportInterface::sendMessage() stores the message. So every sender that builds its mail with the TransportBuilder gets copies: the stock sales senders, Light, payment and return modules, cron and the CLI. A mail that fails to send gets no copy, and nor does a mail sent while Stores > Configuration > Advanced > System > Mail Sending Settings > Disable Email Communications is on. Taking the copy never costs the mail: when it fails, Light logs a warning and the mail goes out as before.

A mail that carries a secret, such as a link or a token the customer can pay or sign in with, must not be kept. Pass 'mrx_no_copy' => true in its template vars and Light keeps no copy of it. Light also skips the payment-link mails of Mollie and Pay., which it knows by their payment_token and paylink vars.

What is kept, and for how longCopy Anchor Link

• The HTML is compressed in MariaDB's COMPRESS() format, about 5 KB for an order confirmation, so an order with five mails takes about 25 KB.
• A copy lives as long as its order. Deleting the order deletes its copies (a foreign key with ON DELETE CASCADE). Deleting the customer's account keeps them, as it keeps the order. There is no setting and no clean-up job.
• An erasure or anonymise flow that changes an order must delete that order's copies as well.
• The table and the classes that read it are internal. Read a copy through the order page, not from your module.

How a mail gets its linkCopy Anchor Link

Mrx_Orders reads the order's copies when it draws the timeline and gives each copy one line:

• The "…email was sent to…" lines of the order, its invoices, shipments and credit memos take the first mail of their own document, and show when that mail went out. A mail counts as the document's own when its template id is the store's sales_email/<kind>/template or guest_template.
• A notified history row (is_customer_notified = 1) takes a copy sent within 10 seconds of the row, before or after, that is not a document's first mail. So write the row right after you send the mail, as Light's cancel does:

if (!$this->cancelNotifier->send($order, $reason)) {
    return false;
}
$this->history->addEvent($order, (string)__('Cancellation email was sent to %1.', $order->getCustomerEmail()), true);

• A copy that no line takes gets a line of its own with its subject and recipient, Email “%1” was sent to %2. A resend from Magento's own order or invoice screen shows this way.

Every copy is reachable from the timeline, with or without a history row of yours. Lines from the order_timeline pool can't open the viewer: a link on a provider line stays a plain link. Orders placed before Light kept copies, and mails whose copy was skipped, keep their lines without a button.

Your module's documentCopy Anchor Link

The same brand kit prints the shop's PDFs. Light renders order confirmations, invoices, credit memos, packing slips, the picklist and return slips from its own templates with dompdf, and every print button, mass action and the accountant ZIP gets that PDF. Your module's own document is a type in the documents pool. It writes only the body; Light adds the letterhead with the logo and company details, the title with the number and date, the footer, the page numbers and the owner's format.

• Engine groups the documents by store view and prints at most 25 in one dompdf run, then merges the runs into one file. A batch of two channels lists one channel's documents, then the other's.
• Each run renders in the frontend area of the documents' store view with a fresh layout, so __() prints in the store's language whichever area asked for the PDF, and the store's theme can override the templates and the CSS.
• Page numbers ("Page 1 of 2") print only when the file holds one document that runs over a page.
• Paper is A4. The text is Inter, with DejaVu Sans for the characters Inter lacks, so "Łukasz" and "Анна" print right; Letter sets its headings in a serif. There is no font setting.
• dompdf sits behind Mrx\Documents\Api\PdfRendererInterface. A shop that runs Gotenberg or mPDF sets a preference for it: render($html, $options) gets one HTML page with its CSS and its fonts as file:// URLs, and returns the PDF bytes. Light merges the runs and hands the stock callers their PDF through Zend_Pdf, so the file needs a classic xref table, not an xref stream.

    public function getLabel(): string
    {
        return (string)__('Credit memos');
    }

    public function getAclResource(): string
    {
        return 'Magento_Sales::sales_creditmemo';
    }

    public function getTemplate(): string
    {
        return 'Mrx_Documents::documents/creditmemo.phtml';
    }

<type name="Mrx\Documents\Model\Pdf\DocumentTypes">
    <arguments>
        <argument name="types" xsi:type="array">
            <item name="order" xsi:type="object">Mrx\Documents\Model\Pdf\Types\OrderType\Proxy</item>
            <item name="invoice" xsi:type="object">Mrx\Documents\Model\Pdf\Types\InvoiceType\Proxy</item>
            <item name="creditmemo" xsi:type="object">Mrx\Documents\Model\Pdf\Types\CreditmemoType\Proxy</item>
        </argument>
    </arguments>
</type>

<?php if ($refundedOn !== '' || $notes !== []): ?>
    <div class="doc-note">
        <?php if ($refundedOn !== ''): ?><p class="doc-paid"><?= $escaper->escapeHtml(__('Refunded on %1', $refundedOn)) ?></p><?php endif ?>
        <?php foreach ($notes as $note): ?><p class="doc-comment"><?= $escaper->escapeHtml($note) ?></p><?php endforeach ?>
    </div>
<?php endif ?>

<type name="Mrx\Documents\Model\Pdf\ItemLines">
    <arguments>
        <argument name="lines" xsi:type="array">
            <item name="default" xsi:type="object">Mrx\Documents\Model\Pdf\Line\DefaultLine</item>
            <item name="bundle" xsi:type="object">Mrx\Documents\Model\Pdf\Line\BundleLine</item>
            <item name="downloadable" xsi:type="object">Mrx\Documents\Model\Pdf\Line\DownloadableLine</item>
        </argument>
    </arguments>
</type>

Light's own document typesCopy Anchor Link

The packing slip lives in another module. Mrx_Documents doesn't know the packing slip or the picklist. Mrx_Orders adds them to the documents pool from its own etc/di.xml, the way your module would:

<type name="Mrx\Documents\Model\Pdf\DocumentTypes">
    <arguments>
        <argument name="types" xsi:type="array">
            <item name="packing_slip" xsi:type="object">Mrx\Orders\Model\Documents\PackingSlipType\Proxy</item>
            <item name="packing_slip_shipment" xsi:type="object">Mrx\Orders\Model\Documents\PackingSlipShipmentType\Proxy</item>
            <item name="picklist" xsi:type="object">Mrx\Orders\Model\Documents\PicklistType\Proxy</item>
        </argument>
    </arguments>
</type>

Its composer.json requires mrx/module-documents, and its etc/module.xml lists Mrx_Documents in the sequence. The body, Mrx_Orders::documents/packing-slip.phtml, draws its own items table instead of Light's parts: a slip shows quantities, and prices only when the owner switches on "Show prices" (mrx_documents/packing_slip/show_prices, per channel, off by default). Both packing slip types read their data from Mrx\Orders\Model\PackingSlip\SlipData, so the slip of an order and the slip of a parcel look the same. Under the customer's note the slip prints the gift messages (Magento_GiftMessage) of the order and of the items on that slip, from the data key gift_messages; without that module the list is empty.

The return slip lives in Returns. Mrx_Returns adds return_slip the same way, and gives it a module gate, so the type leaves the pool while MageOS RMA is off:

<type name="Mrx\Documents\Model\Pdf\DocumentTypes">
    <arguments>
        <argument name="types" xsi:type="array">
            <item name="return_slip" xsi:type="array">
                <item name="type" xsi:type="object">Mrx\Returns\Model\Documents\ReturnSlipType\Proxy</item>
                <item name="module" xsi:type="string">MageOS_RMA</item>
            </item>
        </argument>
    </arguments>
</type>

The customer puts the slip in the parcel, so its body, Mrx_Returns::documents/return-slip.phtml, prints what the warehouse needs to match the parcel to the return: the return number in large type with a Code 128 barcode above it, where to send the parcel, the customer, the order number, the request date, and the items with their quantity, reason and condition. The quantity is the one the owner approved, else the one the customer asked for. The address is the shipping origin when it has a street and a city, else the store address from Business details; a shop with a separate returns warehouse sets the shipping origin, or adds the address with a section (Add a block to a document). The barcode class, Mrx\Documents\Model\Pdf\Barcode\Code128, is internal. "Print return slip" in the More actions of a return links to light/documents/download once the owner has approved the return, and stays there while the parcel travels and after it arrives.

The order confirmation has no stock PDF behind it. No getPdf() hook maps to order, so it prints only through DocumentRendererInterface and light/documents/download, the same path a type of yours takes. "Print order" in the order page's More actions links to the download route with the order's id. The orders list's "Print packing slips", "Print picklist" and "Print order confirmations" ask their route (light/orders/packingslips, light/orders/picklist, light/orders/confirmations) before they open a tab, as "Print invoices" does: the answer says how many orders print and how many were skipped, and carries the link to the PDF with at most 250 ids, the most the download takes. The packing slip skips canceled orders, the picklist skips canceled orders and orders with nothing left to ship, and the order confirmation prints every order, canceled ones too.

The preview lists only types with a sample. The picker's Documents group shows a type only when it can build a sample, through an interface that is internal: Light's order confirmation, invoice, credit memo and packing slip. The picklist is a staff document over many orders, and packing_slip_shipment is the same slip as packing_slip, so neither shows. A type from your module prints and downloads like Light's, but doesn't show in the picker.

Add a block to a documentCopy Anchor Link

A module that adds something to documents it doesn't own, such as the pickup point a parcel goes to, registers a section in the document_sections pool: the argument sections of Mrx\Documents\Model\Pdf\Sections, in the global etc/di.xml. The section implements Mrx\Documents\Api\DocumentSectionInterface and returns the HTML to add, or '' to add nothing. The pickup point example the tests run:

    public function render(Document $document, LayoutInterface $layout): string
    {
        $lines = $this->points[$document->number] ?? [];
        if ($lines === []) {
            return '';
        }
        $escape = static fn (string $text): string => htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

        // Rendered in the document's store view, so the heading is in the customer's language.
        return '<div class="doc-note"><p class="doc-paid">' . $escape((string)__('Pickup point')) . '</p><p>'
            . implode('<br>', array_map($escape, $lines)) . '</p></div>';
    }

Each item of the pool is an array; the fixture's docblock shows its etc/di.xml.

• document takes one type code, or *, and no patterns. The slip of an order (packing_slip) and the slip of a parcel (packing_slip_shipment) are two codes, so a pickup point on both needs two items; the fixture's etc/di.xml has a third for order.
• * includes the picklist, whose number is the moment it was printed and whose language is the admin's. A section meant for customers names its types.
• The section renders in the frontend area of the document's store view, so __() prints in the customer's language. Use doc-note for a box in the owner's format; the rules for a body apply.
• A section that throws is logged and left out, and the document prints without it.
• Light's own types print the sections at all three positions; the packing slip and the picklist, which have no totals, print after_totals after the items. A type of yours prints them only where its body calls the sections closure that Light puts in the block's data, as the packing slip does:

$sections = $block->getData('sections');
$section = static fn (string $position): string => $sections instanceof \Closure ? $sections($position, $document) : '';

Bin locations on the picklistCopy Anchor Link

"Print picklist" on the orders list prints one table over up to 250 selected orders: every product still to ship, with its SKU, name and options, the total quantity and the order numbers. Light keeps no stock locations. A module that knows where products are stored adds a source to the pick_locations pool: the argument locations of Mrx\Documents\Model\Pdf\PickLocations, in the global etc/di.xml, each item an object that implements Mrx\Documents\Api\PickLocationInterface. The example the tests run reads its bins from a list; the fixture also records every call for the test:

    public function getLocations(array $skus, int $storeId): array
    {
        $this->calls[] = [$skus, $storeId];

        return array_intersect_key($this->bins, array_flip($skus));
    }

• getLocations() gets every SKU on the picklist in one call, with the store view the picklist prints for: the main channel's default store view. Return SKU => location, such as "A-03-2", and leave out the SKUs you don't know.
• When any row has a location, the picklist gets a Location column and sorts by it, in natural order, with the rows that have none last. Without locations it sorts by SKU.
• With several sources, the later item in the pool wins for a SKU both know. A source that throws is logged and skipped; the picklist prints with what the others know.

Plugins on the stock PDF classesCopy Anchor Link

While Magento classic is off, an around plugin answers getPdf() of Magento\Sales\Model\Order\Pdf\Invoice, Creditmemo and Shipment and never calls the stock method. The shipment PDF is the packing slip (type packing_slip_shipment, supplied by Mrx_Orders); when that module or the type is missing, the plugin proceeds to the stock PDF. A plugin or a preference on the drawing code behind it (insertOrder(), _drawItem(), insertTotals(), the item renderers pdf.xml lists for invoices, credit memos and shipments) stops running, with no error. The doctor lists each one as pdf_inner_plugin. One thing keeps working: the total models of pdf.xml, which Light reads for the totals (tax, weee and a payment fee print as before). Move what such a plugin added into an item line, or into a document of your own.

PDFs on customer emailsCopy Anchor Link

Light puts its PDFs on the sales emails the customer already gets. The owner picks one setting on the Documents card, "Send the invoice PDF with" (mrx_documents/invoice/send_with, per channel):

• Each invoice goes out once. A shipping confirmation carries the order's invoices that no earlier email carried. With one invoice and two partial shipments, the PDF goes with the first shipment only. When Mollie (Klarna, Billie) makes an invoice per shipment, each shipment carries its own. A resend of a shipping confirmation carries the same PDFs again.
• shipment falls back to "Payment received" for an order with nothing to ship, and for a store whose shipping confirmation is off in Settings > Customer emails. Otherwise no email would carry the invoice.
• An order shipped before it was paid gets a shipping confirmation without a PDF. "Email invoice" on the order page sends the invoice later.
• "Mark as paid" and "Capture" send no email. "Email invoice" in the order's More actions (light/orders/emailinvoice, Magento_Sales::email) sends "Payment received" with the PDF for each invoice that isn't canceled, whatever the setting, unless it is none.
• The order confirmation PDF rides on the order email when the owner switches on "Attach the order confirmation PDF to the order email" (mrx_documents/order/attach, per channel, off by default).
• A body says so with {{depend mrx_has_attachment}}: Light's order, "Payment received" and shipping bodies print "Your invoice is attached as a PDF." or "Your order confirmation is attached as a PDF.". The refund email keeps Magento's body and has no such line.
• Magento classic sends no PDF.

The table mrx_documents_invoice_mailed holds one row per invoice that went out as a PDF, with the shipment whose email carried it, or NULL for "Payment received". A row goes when its invoice is deleted. The table is internal.

How the PDF gets on the email. Each of Magento's sales emails goes out through a sender that builds its message with a SenderBuilder. Light gives seven senders a senderBuilderFactory that makes Mrx\Documents\Model\Email\Attachment\AttachingSenderBuilder: InvoiceSender and Invoice\Sender\EmailSender, ShipmentSender and Shipment\Sender\EmailSender, CreditmemoSender and Creditmemo\Sender\EmailSender, and OrderSender. The shipping pair, for example:

    <virtualType name="MrxDocumentsShipmentSenderBuilderFactory" type="Magento\Sales\Model\Order\Email\SenderBuilderFactory">
        <arguments>
            <argument name="instanceName" xsi:type="string">MrxDocumentsShipmentSenderBuilder</argument>
        </arguments>
    </virtualType>
    <type name="Magento\Sales\Model\Order\Email\Sender\ShipmentSender">
        <arguments>
            <argument name="senderBuilderFactory" xsi:type="object">MrxDocumentsShipmentSenderBuilderFactory</argument>
        </arguments>
    </type>

So every caller of those senders gets the PDFs: the admin, Light's Ship items and Refund, the checkout, cron with asynchronous sending, and the payment modules. Mollie's and Pay.'s own invoice settings keep working, because their invoice emails go through InvoiceSender. The BCC copy carries the same files; a separate "copy to" mail carries them too. Light's tracking update email doesn't go through a sales sender and carries no PDF.

The provider interfaces behind the builder, AttachmentProviderInterface and RecordsSendInterface, are internal in 0.1: only Light's own documents attach. If your module needs to attach its own document to a sales email, ask for it.

The storefront print. "Print invoice", "Print all invoices" and "Print refund" in My Account and in the guest order view open the same PDF the owner prints, inline in the browser, in the order's store language. An after plugin on the four print controllers swaps the print page for the PDF only when the stock controller answered with the page, so the stock check that the customer may see the order still decides. Another customer's invoice id gets the stock redirect. The setting doesn't hide the print: a customer can always fetch an invoice that exists. With Magento classic on, the stock print page comes back.

The return slip on the approval mailCopy Anchor Link

The customer gets the return slip with the mail that tells them the return is approved, so they can pack the parcel straight away. The return's status decides which mail that is, at the moment the mail goes out:

• The status decides. A return the owner creates in the admin gets the slip once it is approved, whatever the setting says, and so does a return that came in before the owner changed the setting.
• Each mail carries one slip, Retourbon-<number>.pdf in Dutch, named in the return's store language. Later status mails ("in transit", "received", "resolved") carry none.
• Both bodies print "Your return slip is attached. Print it and put it in the parcel." under {{depend mrx_has_attachment}}.
• "Return request received" tells a return that waits for the owner from one that is approved on arrival. It prints "We will review your request and get back to you as soon as possible." under {{depend mrx_awaits_review}} and "We have approved your return." under {{depend mrx_approved}}. A theme that overrides customer_new.html keeps both blocks, or an approved return's mail still promises a review.
• An owner who approves with "Send a notification to the customer" unticked sends no mail, so the customer gets no slip. "Print return slip" in the return's More menu still prints it, for the owner to send by hand.
• A slip that fails to render is logged, and the mail goes out without it. Magento classic sends no slip.

The return mails don't go through a sales sender. Returns has its own EmailSender, which replaces MageOS RMA's through a preference on MageOS\RMA\Api\Email\SenderInterface. It overrides upstream's sendRmaEmail() with the same steps and puts the PDF on the message between getTransport() and sendMessage(), with the class the sales builder uses:

            if ($slip !== null && !$this->messageAttacher->attach($transport, [$slip])) {
                // A mail transport module that replaces Magento's message type takes no file, while the body already
                // says the slip is attached.
                $this->logger->warning(
                    'Light Returns: the mail for return ' . $rma->getEntityId() . ' took no return slip'
                );
            }
            $transport->sendMessage();

MessageAttacher is internal, like the providers.

A client formatCopy Anchor Link

A format restyles every email and every PDF of the shops that pick it. It sets the type, the spacing and where the accent goes; the logo, the accent colour and the footer stay the owner's settings. An agency that gives its clients one house look ships it as a format in a module of its own.

A format is an item in the formats pool, in the global etc/di.xml, because mails render in the storefront, the admin, cron and the REST API. Acme_LightProof adds one:

<type name="Mrx\Documents\Model\Format\Formats">
    <arguments>
        <argument name="formats" xsi:type="array">
            <item name="acme" xsi:type="array">
                <item name="label" xsi:type="string" translate="true">Acme</item>
                <item name="description" xsi:type="string" translate="true">Rounded buttons and a tinted item table.</item>
                <item name="email_inline_css" xsi:type="string">Acme_LightProof::css/email-acme.css</item>
                <item name="sort_order" xsi:type="number">40</item>
                <item name="module" xsi:type="string">Acme_LightProof</item>
            </item>
        </argument>
    </arguments>
</type>

The code becomes the class mrx-f-acme on the mail's wrapper table and on the PDF's body, so every rule in the format's files starts with it. A code is a plain identifier, a lower-case letter and then letters, digits or _ (2 to 32 characters); the pool skips any other. To change or remove one of Light's formats, use its key, as Changing Light for one shop shows.

The email fileCopy Anchor Link

email_inline_css restyles the email classes and uses the two tokens, with the rules of your own CSS: a token as a plain value, no {{var}} and no var().

Check the path in email_inline_css once in a mail catcher. A file Magento can't find strips the inline styles from every mail of every shop that picks the format, Light's own styles included.

.mrx-f-acme .header { border-bottom: 4px solid __MRX_ACCENT__; border-radius: 16px 16px 0 0; }
.mrx-f-acme .button .inner-wrapper td, .mrx-f-acme .button .inner-wrapper td a { border-radius: 999px; }

The header inlines it after Light's own file, so a rule of the same weight wins:

{{inlinecss file="Mrx_Documents::css/email-inline.css"}}
{{depend mrx_format_inline_css}}{{inlinecss file=$mrx_format_inline_css}}{{/depend}}

Style only the classes and tokens of the surface snapshot (its email-class and email-token lines). Light may rename any other class in a minor release, and your rule then styles nothing.

The PDF fileCopy Anchor Link

pdf_css names a frontend CSS file that Light puts after its base.css in every PDF. It restyles the doc-* classes and takes the same two tokens. Light's Bold format starts like this:

.mrx-f-bold .doc-letterhead { border-top: 4mm solid __MRX_ACCENT__; }
.mrx-f-bold .doc-letterhead td { padding-top: 5mm; }
.mrx-f-bold .doc-title { font-weight: 700; }
.mrx-f-bold .doc-items th { background: __MRX_ACCENT__; color: __MRX_ACCENT_TEXT__; border-bottom: 0; }

• A format without pdf_css, such as Acme's, prints its PDFs in Light's base look.
• dompdf has no flexbox or grid. Lay a PDF out with tables, as base.css does.
• dompdf reads files only from Light's module folder, pub/media and its font cache, so a font file inside your module doesn't load. Use Inter, which Light declares in the weights 400, 500, 600 and 700, or a core font with a DejaVu face behind it, as Letter's headings do with Times, 'DejaVu Serif', serif. A core font alone prints ? for a letter such as the Ł of Łukasz.
• A PDF is always light. A prefers-color-scheme rule in pdf_css never applies.

How an agency adjusts, light to heavyCopy Anchor Link

Start at the top and go one step down only when the step above can't give the client what they ask for. Each step down leaves more for you to check at every Light upgrade.

1. The settings screen. Settings > Emails & documents sets the format, the accent colour and the footer text per channel, and the footer text per language. The logo comes from Business details > Logo and branding, the company lines from Business details. You deploy nothing, and an upgrade keeps all of it.
2. A client format. A module with one or two CSS files, as in A client format. The owner picks it on the same screen, and it keeps working across releases as long as it styles the classes and tokens of the snapshot.
3. A theme override of one file. Copy one of Light's files into the store's frontend theme and change the copy: app/design/frontend/<Vendor>/<theme>/Mrx_Documents/email/header.html for the email header, app/design/frontend/<Vendor>/<theme>/Mrx_Documents/templates/documents/invoice.phtml for the invoice's body. Every store view on that theme gets the copy. From then on Light's fixes to that file skip the shop, so compare the two after each upgrade. A header copy keeps the stock nesting (table.wrapper > td.wrapper-inner > table.main > td.main-content) and both {{inlinecss}} lines, or the bodies and the format lose their styles. An invoice copy reads the keys of the invoice's data, which are internal.
4. Magento's advanced screens. A template saved in Marketing > Email Templates and picked in the configuration replaces Light's file for that scope. It gets no fixes, and no texts from Settings > Customer emails. Keep this for the one mail the steps above can't reach.

What stays in Magento's advanced screensCopy Anchor Link

Light doesn't rebuild these screens. They work as in any Magento shop, and the link "Open in advanced view" on Settings > Emails & documents leads to Stores > Configuration > Sales > Emails and documents (Light), where "Magento classic" lives.

What the owner seesCopy Anchor Link

• Simple mode. Settings > Emails & documents: the format cards (yours among them), the accent colour and the footer text, each per channel, the footer text per language, a preview on desktop or phone, and a test email to the admin's own address. The preview picker lists every customer email by group: Orders, Account, Returns, then Other modules, which holds the pool's emails without a group and every other module's frontend HTML template for customers, rendered with the newest order's variables. "Edit texts" next to the picker opens the email in Settings > Customer emails. When the store has no invoice or credit memo yet, "Payment received" and "Refund confirmation" show an unsaved example made from the newest order. The preview's Documents group lists the types of the documents pool that can build a sample and that the admin may see, "Order confirmations (PDF)", "Invoices (PDF)", "Credit memos (PDF)" and "Packing slips (PDF)" for Light's own, each as a sample in the look on screen: the store view's newest document of that type, or, when it has none, an unsaved example built from an order (an invoice from an order that waits for one, a credit memo that refunds a paid order in full). The order confirmation shows the newest order that isn't canceled, the packing slip the newest order with something left to ship. Only Light's own types build a sample, because the interface for it is internal, so a type you register in the pool prints and downloads like the others but doesn't show in the picker. The Documents card holds three controls, each per channel: Order confirmation, "Attach the order confirmation PDF to the order email" (off); Invoice PDF, "Send the invoice PDF with" (the shipping confirmation); Packing slip, "Show prices" (off). On an order, More holds "Print packing slip" unless the order is canceled, "Print order", "Print invoice", "Email invoice" once the order has an invoice and, once the order has a refund, "Print credit memo"; a shipment's own menu holds "Print packing slip" for that parcel. Each downloads the PDF. The orders list's bulk actions include "Print packing slips", "Print picklist" and "Print order confirmations". On a return, More holds "Print return slip" from approval onward.
• Advanced mode. Stores > Configuration > Sales > Emails and documents (Light) holds the same fields and "Magento classic", which gives emails and PDFs Magento's own look back. The stock print buttons and mass actions, "Print All" included, print Light's PDFs.

ACLCopy Anchor Link

Mrx_Documents::documents guards the settings screen, its preview and its test email. The preview and the test of an order email, and of any email under Other modules that isn't in the emails pool, also need Magento_Sales::sales_order, and each PDF in the picker needs the type's own getAclResource(): Magento_Sales::sales_invoice for the invoice, Magento_Sales::sales_creditmemo for the credit memo. An example built from an order, when the store has no invoice or credit memo yet, also needs Magento_Sales::actions_view, because it prints that order's customer; without it the preview says there is nothing to show yet. A format has no resource of its own. light/documents/download asks for the type's getAclResource(): Magento_Sales::sales_invoice for invoice, Magento_Sales::sales_creditmemo for creditmemo, and Magento_Sales::actions_view for order, the packing slips and picklist, as do the bulk routes light/orders/packingslips, light/orders/picklist and light/orders/confirmations; return_slip asks for MageOS_RMA::rma_manage, the resource of the returns screens. View email and its route, light/documents/sentemail, need Magento_Sales::actions_view, the resource of the order page; the route answers a copy only for the order it belongs to.

Check itCopy Anchor Link

• bin/magento mrx:light:doctor --module=<your module>: email_shell (a body without the includes), email_inline_style (more than 3 style attributes), wrong_area (an item of emails, formats, documents or another global pool in etc/adminhtml/di.xml), pdf_inner_plugin (a plugin or preference on the stock PDF drawing code), and for the shop email_shell_config (a header or footer saved in the database or pointing at a template that doesn't exist) and email_css (a missing or stale email CSS file).
• Send the mail and open it in Mailpit, in each format and in dark mode. Its Text tab shows the plain-text part.
• Send your mail about an order, open the order and click View email on its line. SELECT subject, UNCOMPRESS(html_body) FROM mrx_documents_sent_email WHERE order_id = <id> shows what was kept.
• Print one document and a batch from two store views, in each format. pdftotext -layout <file> - shows the text; pdffonts <file> should list Inter, and DejaVu only where a character needs it.

PitfallsCopy Anchor Link

• A theme that overrides Magento's header.html and footer.html under Magento_Email doesn't change a Light mail: the shell ids are mapped to Light's own before the theme's file is looked up. Style the email classes in a format instead.
• A theme that overrides documents/page.phtml reads the internal Brand class, which may change in a minor release.
• After an upgrade the deployed copies of the email CSS are old until setup:static-content:deploy runs; the doctor reports email_css.
• Replacing the invoice, creditmemo or packing_slip_shipment item with a type of your own switches Light's PDF off for the stock getPdf() callers: they get the stock PDF back, because the hook also needs to print the invoices, credit memos or shipments it was handed rather than ids. To change the invoice's look, override Mrx_Documents::documents/invoice.phtml in the store's theme.
• Another module that sets its own senderBuilderFactory on one of the seven sales senders, such as a PDF-attachment extension, replaces Light's: the module that loads last wins, and the other's PDFs stop without an error. Keep one of the two.
• A mail transport module that swaps Magento's EmailMessage for a message of its own takes no return slip, while the body still says "Your return slip is attached.". The log gets a warning: Light Returns: the mail for return 140 took no return slip.
• Another module with its own preference for MageOS\RMA\Api\Email\SenderInterface replaces Returns' sender: the return slip, the store's contact details and the owner's message leave the return mails without an error. Keep one of the two.
• Two customer mails about one order sent within 10 seconds of each other, whose history rows are written in the other order, swap their View email links. Write each row straight after its own send.
• dompdf reads TrueType fonts only. A WOFF2 file in a @font-face falls back to DejaVu Sans without a warning, as does a weight you didn't declare.
• The first PDF fills the font cache in var/mrx_documents/fonts, and dompdf rewrites a file there for every new font. The PHP-FPM user must own it: a PDF printed from a root shell leaves files the shop can't rewrite.