Invoice notification contract

Purpose: a business sends an invoice to its customer. Baseline: App\Mail\invoice and resources/views/emails/invoice/invoice.blade.php. Referenced queue callers include emailsController::sendinvoice and SendSelectedInvoices. See email-catalog.md for exact source lines; the Mailable definition alone does not prove production delivery.

Suggested subject: Invoice #{{invoice_number}}. This preserves the current subject pattern.

Suggested preheader: Invoice {{invoice_number}} from {{business_name}}. {{currency}} {{amount_due}} due by {{due_date}}.

Portable placeholder contract

Token	Existing Laravel source / derivation	Requirement
{{logo_url}}	Deployment asset value for the existing Built app_name PNG; not a business logo	Optional deployment override; default is the verified project HTTPS Built PNG. Replace its src with an approved URL or matching CID if needed.
{{preheader}}	Text assembled from invoice->invoice_number, business->name, invoice->fx_currency, invoice->amount_due and invoice->end_date	Required; escaped text
{{business_name}}	$business->name	Required; repeated in heading, note label and sign-off
{{invoice_number}}	$invoice->invoice_number	Required; preserve as text, including leading zeros
{{currency}}	$invoice->fx_currency	Required; do not substitute business/base currency
{{amount_due}}	number_format($invoice->amount_due, 2)	Required; same due amount, not invoice total or amount_paid
{{due_date}}	$invoice->end_date	Required; format the same value without inventing a deadline
{{invoice_url}}	$invoice->link	Required; validated complete existing URL
{{invoice_action_label}}	$can_pay ? 'View and pay invoice' : 'View invoice'	Required derived label; never accept arbitrary user-supplied label
{{invoice_action_context}}	$can_pay ? 'Opens your invoice, where you can review the details and payment options.' : 'Opens your invoice so you can review the details.'	Required derived explanation
{{merchant_message}}	$message	Optional; remove marked table if absent. Plain text contract with newlines preserved; see rich-message decision below

There is no new per-recipient greeting in this template. Recipient addresses stay with the existing caller's Mail::to/BCC logic. The sample customer's identity in the workspace header describes the audience and is not a new Laravel data dependency.

States and existing values outside the HTML

Payment enabled: can_pay=true, label “View and pay invoice”; the existing invoice->link opens invoice details with available payment options.
View only: can_pay=false, label “View invoice”; no implied payment capability. The URL still comes from invoice->link.
Merchant message present/absent: the ready HTML contains a marked optional table. With no message, remove the whole table and its spacing. With a message, preserve all meaningful content. This portable draft escapes text and preserves line breaks; an existing HTML message requires conversion that retains link destinations or separately sanitized Blade markup.
send_attachment=true/false: the Mailable always attaches the invoice PDF; the flag adds InvoiceAttachement files. The HTML wording stays valid in both states. The preview includes an additional-attachment example note without inventing a count or size.
$send_tome is accepted by the constructor but is unused in build(); do not make up new recipient/copy behavior. Keep any caller-managed BCC handling as it is.
$invoice->invoice_color is deliberately retained as a deferred integration value. It has no portable placeholder because it is not used in first-draft HTML; the user approved Built styling as primary and will revisit merchant color as secondary later.
$invoice->items, taxes, index and send_attachment remain PDF/attachment inputs. Do not drop them when changing only the HTML view. Existing PDF generation and post-send transport-acceptance recording are outside the design change.

URL and legacy fields

invoice_url maps to invoice->link, not a new checkout endpoint. The current link can be a short URL generated by InvoiceWasCreated, which builds a destination at /viewinvoice/{uuid}. The legacy mailinvoiceJob separately builds button.link from /viewinvoice/{enc_id}; it is an older contract and is not interchangeable without investigation. Neither button.link nor a second payment_url token is needed for this current Mailable. The sign-in template's link/resetLink fields belong to a different notification.

Keep the current business From name and Reply-To fallback (business email, otherwise owner email), the subject pattern and attached PDF. Do not wire the sample preview-action.html URL into Laravel. Every populated demo action is a local explanation, not an application endpoint.

Plain text and integration

ready/invoice.txt is the portable text alternative. Populated .txt files sit beside each state preview. In Blade, use the same actual values and conditional message section in a text view. Do not include the optional section's token when the message is absent.

Use a dedicated full-document Blade view, convert portable token names explicitly and preserve existing data bindings. The raw baseline message output must not be copied as an untrusted raw HTML slot. Refer to integration-notes.html for escaping, URL validation, images, provider limitations and email-client testing.

Full-view merchant-note alias

When converting Markdown to a complete regular HTML view, explicitly bind the private constructor message to a nonreserved name such as invoice_message. Map merchant_message to that alias and keep its visibility predicate separate from rich-text normalization. Laravel's $message mail helper is needed for native image embedding and must not be treated as merchant text. This is a migration detail, not a claim that the existing Markdown body is broken. Apply the same note and condition in plain text; retain all PDF and extra-attachment bindings.