Sending rendered reports by mail: the mailing segment, mailers, mail templates and the mail queue.

A rendered report usually has somewhere to go: back to the caller as Base64 or as a URL, straight into a print task, or into the mailbox of whoever needs the document. Report Mailing is that last destination. A render request carries an optional mailing segment, and once the render succeeded VeloxFactory sends an HTML mail through a configured mailer, using a configured template, with the PDF attached and, if you want it, an xlsx export of the same data.

Mailing is an addition to a render, never a condition of it. A request without a mailing segment is a plain render, and a mail that fails never turns a successful render into an error.

The three parts

Mailing is built from three things you configure once and one thing you send per render.

Mailing from a render request

The mailing segment is optional and sits next to the fields you already know:

{
    "outputType": "base64",
    "parameters": { "P_ORDER_NO": "4711" },
    "createPrintTask": false,
    "createHistoryRecord": true,
    "mailing": {
        "mailer": "Office SMTP",
        "mailTemplate": "Report Delivery",
        "to": ["disposition@example.com", "[data.first.customerEmail]"],
        "cc": [],
        "bcc": ["archive@example.com"],
        "contactName": "[data.first.customerName]",
        "includePdf": true,
        "pdfFileName": "Order_[parameters.P_ORDER_NO]",
        "includeExcel": true,
        "includeParameters": true,
        "excelFileName": "Data_[traceId]",
        "sendAsync": false
    }
}

mailer and mailTemplate accept either the numeric ID or the unique name of the record, so a request stays readable. Only active records are resolved.

The one combination that is refused up front is outputType: "preview" together with mailing: a preview render deletes its own file immediately, so there would be nothing to attach.

The Excel attachment

includeExcel turns the data of the render into a real xlsx, not a CSV with a different name. The rows come from what was actually rendered, which matters for reports fed by an SQL adapter: there the rows only exist in the render result, never in your request.

The sheet has a header row in the report's accent colour, frozen below the header, with an auto filter across the table. Columns are typed from the report's field definitions, so an integer is a number, a date is a real Excel date and a decimal keeps its format. For a dynamic array without field definitions the type is inferred from the values. Rows with differing keys are merged into one header, in first-seen order, and missing values stay empty.

With includeParameters the parameters are printed above the table, so the recipient can see what the report was asked for without opening the mail again.

If the render produced a history record, the xlsx is stored on it and stays downloadable from the history record page. It is cleaned up by the same retention as the PDF.

Placeholders in recipients and attachment names

Subject and body are placeholder-driven, and so are the recipients, the contact name and the attachment names. They all accept the same catalog, which is what makes mailing useful for data that only exists after the render.

Every route that takes recipients accepts them: the mailing segment of a render, POST /report-history-record/{id}/mail, POST /report-mail-task and the repeat endpoint. The failure recipients of a schedule are the exception, they are plain addresses, because a run that failed has no render to resolve against.

"to": ["[data.first.customerEmail]"],
"contactName": "[data.first.customerName]",
"pdfFileName": "Lieferschein_[parameters.P_ORDER_NO]_[now.date]"

For a report with an SQL adapter, [data.first.<column>] addresses the rows the query fetched. The recipient list is therefore a result of the render, not an input to it.

A few rules are worth knowing:

Without a requested name the attachment is called like the stored file, which is the trace id plus its extension.

Immediately or through the queue

By default the mail is sent while the request is still open. The response then already tells you whether it went out. That is the right mode for a single document and a fast relay.

sendAsync: true creates the mail task, hands it to the queue and answers immediately. The mail is sent by a Horizon worker, the task moves from Pending to Sent, and a failure is retried with backoff before it ends as Error. Use it for bulk runs and for slow or unreliable SMTP servers, where waiting for the transport would block the render.

There is a third case you do not ask for: if the mailer's rate limit is exhausted, a synchronous send is converted into a delayed queued send instead of failing. The mail is not lost, the response says so, and the task shows when it will go out. See the Mailers page for the windows.

Mailing from the frontend

The same settings are available in four places in the UI, built from one shared block of fields, so they look and behave identically everywhere.

In the configuration modals the mailing settings live in the session alongside the rest of the output settings, and the values are kept even while the toggle is off, so switching mailing off for a moment loses nothing. The file name fields appear only while their attachment switch is on.

After a render the notification says what happened to the mail. A mail that did not go out as configured turns the success notification into a warning instead of hiding the problem.

The block is only rendered at all when the current user may create mail tasks and at least one active mailer and one active template exist. Nobody is offered a button that cannot work.

On a schedule

A mail does not need a caller. A render job in the Job Scheduler carries the same mailing settings as a render request, so a schedule puts the shift report in a mailbox at six every morning without anybody asking for it.

Two things work differently from an interactive send. The schedule's owner and API token decide what may go out: the token needs report-mail-task:create, and a revoked token or a deactivated owner parks the schedule rather than mailing. And placeholders are resolved at the moment the run fires, so [now.date] in a subject line or an attachment name carries the date of that run, not the date the schedule was saved.

Every run is logged with its trace id. A mail task that ends in Error, or anything reported in meta.mailing, marks the run as a warning, so a schedule whose mail is not arriving is visible in the run log without opening the Mail Queue.

The Mail Queue

Every send attempt, synchronous or queued, is recorded as a Report Mail Task. The overview lives in the main menu under Mail Queue and is a regular VeloxFactory lookup with the usual filters and the usual session-persisted state.

A mail task keeps what was actually sent, not just what was requested: the resolved recipients, the rendered subject, the rendered body and the names of the attachments. The detail page shows the mail exactly as the recipient received it, rendered in an iframe from the stored HTML, whitelabeling included.

Repeat resends a task. It opens a dialog in which mailer and recipients can be changed before sending, so a mail that went to the wrong address is corrected rather than cloned. Subject and body are re-rendered from the current template when the history record still exists, otherwise the stored snapshot is reused. The repeated task gets its own trace id, derived from the original.

The same table also appears on the Report History Record page, so the mails belonging to one document are visible where the document is.

Retention

Mail tasks are cleaned up by the Purge Job, the consolidated cleanup schedule of the Job Scheduler. It removes print tasks and mail tasks before the history records they reference, so nothing is deleted out from under a reference. How long mail tasks are kept is a retention on that schedule, editable in the frontend or through the API like everything else; an empty value switches the step off entirely.

The same work is available as a standalone command:

php artisan report-mail-tasks:purge --days=30

Attachments are not owned by the mail task. The PDF and the xlsx belong to the history record and are removed by its retention step, or, if no history record was created, by the orphaned-file step.

The API

Besides the mailing segment on POST /report-config/{id}/render, mailing has endpoints of its own.

A render that mailed something returns the mail task in its response, and anything noteworthy about the mailing in meta.mailing:

AI assistants

The MCP server exposes mailing the same way it exposes printing: the mailing segment is part of the render tool, and mail tasks, mailers and templates have their own tools. Because mailer and template are resolved by name, an assistant can pass what a person said. Render the delivery note for order 4711 and mail it to dispatch is one call.

Permissions

Mailing has three permission scopes, each with the usual read, create, update, delete and full.

report-mail-task:create is the one that matters for sending. It is checked at the start of a render, before anything is rendered, so a user without it gets a clear refusal instead of a wasted render.

Mail graphics are Common Report Resources, so maintaining them uses common-report-resource:*. That permission also covers the logos printed on labels, which is the price for uploading a logo once rather than twice.

A mail needs an account to go out through. Mailers are that account as master data: one record per SMTP mailbox or relay, with its host, its credentials, the address it sends from, and the limits your provider actually enforces. Every mail VeloxFactory sends goes through one of these records.

The MAIL_* keys in the environment file are Laravel's own fallback mailer and are deliberately not used by report mailing. Mail configuration belongs in the application, where it can be changed, tested and audited without a deployment.

Where to find it

Mailers live in the main menu under Configuration → Mailers. The overview is a regular VeloxFactory lookup: search over name, host, sender address and description, filters for transport, active state, tested state, creator, updater and creation date, sortable columns, and the filter state kept in your session.

New opens the create form, the pencil on a row opens an existing record. Deleting is done from the edit page.

The fields of a mailer

Testing a mailer

A new or changed mailer starts as Unapproved. The edit page has a Send Test Mail button that sends a short message through exactly the configuration you just saved, to your own address by default. On success the mailer flips to Approved, on failure the transport's own error message is shown, which is usually enough to see whether it was the port, the credentials or the TLS mode.

This mirrors how report connections are verified, and it works the same way: the status is information, not a gate. A mailer that has never been tested can still be used, it is simply not marked as proven.

A test mail consumes a rate limit slot like any other mail, so the counter stays honest. If the limit is exhausted, the test is refused with the waiting time instead of being sent.

Rate limits

Providers cap outbound mail, and they all cap differently. Exceeding the cap does not produce a polite error, it produces a blocked account, so the limits belong on the mailer, next to the credentials they protect.

Each mailer has three independent windows, each of them optional:

An empty field means the window is not enforced. All three empty means the mailer sends unthrottled. Check your provider's documentation and configure slightly below its cap, because the windows here are fixed rather than sliding.

A slot is spent per message, not per recipient: a mail to five people costs one slot, which is how providers count as well.

When a slot is not available, VeloxFactory does not drop the mail:

The edit page shows the remaining slots per configured window, so a run that is about to hit a cap is visible before it does.

Counters are per mailer and per installation. Two VeloxFactory instances sharing one SMTP account do not share a counter.

Name resolution and deletion

A render request may address a mailer by its numeric ID or by its unique name, and only active records resolve. An unknown or inactive name is refused with a clear message before anything is rendered, rather than silently falling back to some default mailer.

A mailer cannot be deleted while a mail task still references it, so the history of what was sent stays intact. To retire a mailbox, switch the record to inactive: it disappears from every picker and stops resolving, while everything that was sent through it keeps its record.

The API

Mailers are a regular API resource under /api/v1/mailer, with the same envelope, the same audit segment and the same error format as every other resource.

A mailer resource is returned as:

{
    "model": "Mailer",
    "id": 1,
    "name": "Office SMTP",
    "transport": "smtp",
    "host": "smtp.office365.com",
    "port": 587,
    "scheme": "smtp",
    "username": "reports@example.com",
    "fromAddress": "reports@example.com",
    "fromName": "Shipping Department",
    "replyTo": "support@example.com",
    "timeout": 30,
    "localDomain": null,
    "rateLimitPerMinute": 30,
    "rateLimitPerHour": 500,
    "rateLimitPerDay": null,
    "rateLimitRemaining": { "minute": 28, "hour": 471 },
    "isActive": true,
    "mailerTested": true,
    "status": "Approved",
    "description": "Shipping mailbox"
}

The password is never part of the response.

AI assistants

The MCP server exposes the same operations as tools, including the test. An assistant can create a mailer from a provider's documented settings and verify it in the same conversation.

Permissions

Mailers use the standard permission scheme and have their own Mailers section in the user editor.

Credentials are readable to anyone with mailer:read in the sense that the username is shown; the password is not, on any path. Treat mailer:update as an administrative permission.

A mail needs something to say. Mail Templates are the subject and the body, written once and reused by every render that mails a document. They are edited in a WYSIWYG editor, so nobody has to write HTML, and everything variable is a placeholder that VeloxFactory fills in at send time: the trace id, a parameter of the request, the name of the report, a column of the data that was rendered.

A template decides the content. The surrounding mail, a plain card in your application's colours, is built by VeloxFactory, and a template can override parts of it when a customer needs their own look.

Where to find it

Mail Templates live in the main menu under Configuration → Mail Templates. The overview is a regular VeloxFactory lookup with search over name, subject and description, a filter for the active state and the usual audit filters.

A template has a unique name, which is what a render request may use instead of the ID, a subject, a body and an active flag. An inactive template stays in the master data but is no longer offered and no longer resolves.

The editor

The body is written in a rich text editor built into VeloxFactory. No add-on, no external service, and nothing to learn: the toolbar does what a toolbar does.

Pasting is deliberately plain text. Formatted content dragged in from Word or a browser is the single most common reason a mail looks broken in one client and fine in another, so the editor strips it and keeps the words.

Whatever the editor produces is cleaned on the server against an allowlist before it is stored. That is not a formality: it is what guarantees that a template cannot carry a script, a tracking pixel or an arbitrary external image, no matter what was pasted into it.

Placeholders

Anything in square brackets is replaced when the mail is built. Both the subject and the body support them.

Hello [contactName], attached is your report [report.name] with the trace ID [traceId], rendered on [now.dateLocale].

The Placeholders button opens a dialog listing every token that is available, grouped, with a description and an example, and each one copyable with a click. Opened from a template that is tied to a report, the parameter and field tokens are expanded to the real names of that report.

The same catalog is available beyond subject and body: recipients, contact name and the names the attachments carry in the mail accept placeholders too. See the Report Mailing page for how that behaves.

Graphics

Mail graphics are the Common Report Resources you already maintain, the same PNG and JPEG files the reports use. A logo is uploaded once and serves both a printed label and a mail.

Insert one with the image button, or type its placeholder, for example [image.logo_dark]. Both produce the same thing, and the editor shows the graphic while you write.

At send time the graphic is embedded into the mail as an inline attachment, not linked from a server. That matters for two reasons: the mail is self-contained, so it also works for a recipient outside your network, and no client shows a load external images bar or treats it as a tracking pixel.

A Common Report Resource that a template embeds cannot be deleted or renamed while the template uses it. The refusal names the template, so it is clear what would break.

Whitelabeling

By default every mail looks the same: a card in the colours of your VeloxFactory installation, read straight from the application's stylesheet, with a coloured header bar and a footer. Change a colour in the frontend and the mails follow, without touching a template.

When one customer or one process needs something else, a template can override parts of that frame. Each override has its own switch, and switching it off returns that part to the global default:

Preview

The Preview button renders the template inside the real mail frame, with example values or against an existing history record, and shows it in a dialog. It is the same rendering path the actual mail uses and the same one the Mail Queue uses to show a sent mail, so the three cannot drift apart: what the preview shows is what is sent and what is archived.

Use it after every change. It is the fastest way to catch a placeholder that resolves to nothing, a table that lost its borders or a whitelabel colour that makes the text unreadable.

The API

Mail Templates are a regular API resource under /api/v1/mail-template.

Unknown placeholders in a stored template are not an error. They are returned as messages, so an integration can warn without being blocked.

AI assistants

The MCP server exposes the same operations, including the placeholder catalog. An assistant can therefore write a template that uses the real parameter names of a specific report, and preview it before anyone sends it.

Permissions

Mail Templates use the standard permission scheme and have their own Mail Templates section in the user editor.

Uploading the graphics a template uses is a separate permission, common-report-resource:create and :update, because those files are shared with the reports.