Report Mailing: sending renderings by mail

A rendered report usually has somewhere to go. Until now VeloxFactory could hand itgo: back to the caller as Base64,Base64 or as a URL orURL, straight into a print task.task, Reportor Mailing adds the fourth destination: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.

NothingMailing aboutis renderingan changes.addition to a render, never a condition of it. A request without a mailing segment behavesis exactlya asplain it always did,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 jobs as the PDF.

Placeholders in recipients and attachment names

Subject and body have always beenare placeholder-driven.driven, Inand theso final implementationare 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.

"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 threefour places in the UI, built from one shared block of fields, so they look and behave identically everywhere.

In the two 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 purgedcleaned likeup by the Purge Job, the consolidated cleanup schedule of the Job Scheduler. It removes print tasks, on their own scheduletasks and mail tasks before the history records they reference: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

The retention is configured with PURGE_MAILTASKS_DAYS and the job runs nightly. Attachments are not owned by the mail task;task. theThe PDF and the xlsx belong to the history record and are removed by its ownretention retention,step, or, if no history record was created, by the orphaned-file purge.step.

The API

Besides the mailing segment on POST /report-config/{id}/render, mailing has two 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 addshas 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.