Documentation / @zerotal/notifications / MailMessage

Class: MailMessage

Defined in: notifications/src/messages/MailMessage.ts:122

The fluent representation a notification returns from toMail() — symmetric with toSms() → SmsMessage and toSlack() → SlackMessage. Compose a branded email from a greeting, lines, and an optional call-to-action button, or drop to .html() for a fully custom body.

Lines accept inline styling. Pass a TextStyle to style a whole line, or use the callback form to mix differently-styled runs within one line.

The recipient is normally the notifiable (its email), so you don't set to() — MailChannel fills it in. Use to()/cc()/bcc()/from()/replyTo() only to override.

Example

toMail(n: Notifiable): MailMessage {
  return new MailMessage()
    .subject("Your order shipped")
    .greeting(`Hi ${n.name ?? "there"},`, { bold: true })
    .line("Your order is on its way.")
    .line("Action required", { bold: true, color: "#dc2626", size: 18 })
    .line((t) => t.text("Tracking number: ").bold(this.order.tracking))
    .action("Track package", `https://app.test/orders/${this.order.id}`)
    .line("Thanks for shopping with us!");
}

Constructors

Constructor

new MailMessage(): MailMessage

Returns

MailMessage

Methods

subject()

subject(text): this

Defined in: notifications/src/messages/MailMessage.ts:139

Parameters

text

string

Returns

this

greeting()

Call Signature

greeting(text): this

Defined in: notifications/src/messages/MailMessage.ts:149

Opening line, e.g. "Hi Ada,". Defaults to "Hello," when omitted. Accepts the same styling forms as line(): a plain string, a string + TextStyle, or a RichLine callback for mixed runs.

Parameters

text

string

Returns

this

Call Signature

greeting(text, style): this

Defined in: notifications/src/messages/MailMessage.ts:150

Opening line, e.g. "Hi Ada,". Defaults to "Hello," when omitted. Accepts the same styling forms as line(): a plain string, a string + TextStyle, or a RichLine callback for mixed runs.

Parameters

text

string

style

TextStyle

Returns

this

Call Signature

greeting(build): this

Defined in: notifications/src/messages/MailMessage.ts:151

Opening line, e.g. "Hi Ada,". Defaults to "Hello," when omitted. Accepts the same styling forms as line(): a plain string, a string + TextStyle, or a RichLine callback for mixed runs.

Parameters

build

(t) => void

Returns

this

salutation()

Call Signature

salutation(text): this

Defined in: notifications/src/messages/MailMessage.ts:161

Closing line, e.g. "Regards,". Defaults to "Regards,". Accepts the same styling forms as line().

Parameters

text

string

Returns

this

Call Signature

salutation(text, style): this

Defined in: notifications/src/messages/MailMessage.ts:162

Closing line, e.g. "Regards,". Defaults to "Regards,". Accepts the same styling forms as line().

Parameters

text

string

style

TextStyle

Returns

this

Call Signature

salutation(build): this

Defined in: notifications/src/messages/MailMessage.ts:163

Closing line, e.g. "Regards,". Defaults to "Regards,". Accepts the same styling forms as line().

Parameters

build

(t) => void

Returns

this

line()

Call Signature

line(text): this

Defined in: notifications/src/messages/MailMessage.ts:176

Add a paragraph. Lines before action() render above the button; lines after, below it.

Plain: .line("Welcome aboard.")
Whole-line style: .line("Heads up", { bold: true, color: "#dc2626", size: 18 })
Mixed runs: .line((t) => t.text("Code: ").bold("AB12").color(" (expires soon)", "#6b7280"))

Parameters

text

string

Returns

this

Call Signature

line(text, style): this

Defined in: notifications/src/messages/MailMessage.ts:177

Add a paragraph. Lines before action() render above the button; lines after, below it.

Plain: .line("Welcome aboard.")
Whole-line style: .line("Heads up", { bold: true, color: "#dc2626", size: 18 })
Mixed runs: .line((t) => t.text("Code: ").bold("AB12").color(" (expires soon)", "#6b7280"))

Parameters

text

string

style

TextStyle

Returns

this

Call Signature

line(build): this

Defined in: notifications/src/messages/MailMessage.ts:178

Add a paragraph. Lines before action() render above the button; lines after, below it.

Plain: .line("Welcome aboard.")
Whole-line style: .line("Heads up", { bold: true, color: "#dc2626", size: 18 })
Mixed runs: .line((t) => t.text("Code: ").bold("AB12").color(" (expires soon)", "#6b7280"))

Parameters

build

(t) => void

Returns

this

action()

action(text, url): this

Defined in: notifications/src/messages/MailMessage.ts:187

A call-to-action button. At most one per message.

Parameters

text

string

url

string

Returns

this

html()

html(content): this

Defined in: notifications/src/messages/MailMessage.ts:194

Provide a fully custom HTML body, bypassing the greeting/line/action template.

Parameters

content

string

Returns

this

text()

text(content): this

attach(attachment): this

Defined in: notifications/src/messages/MailMessage.ts:233

Attach a file to the message.

Parameters

attachment

MailAttachment

Returns

this

Example

.attach({ filename: "invoice.pdf", content: pdfBytes, contentType: "application/pdf" })

attachFile()

attachFile(path, options?): Promise<MailMessage>

Defined in: notifications/src/messages/MailMessage.ts:245

Attach a file read from disk. Reads the bytes when called, so the message is self-contained by the time a driver sends it.

Parameters

path

string

options?

filename?

string

contentType?

string

Returns

Promise<MailMessage>

Example

await new MailMessage().subject("Your invoice").attachFile("./storage/invoice.pdf");

embed()

embed(cid, attachment): this

Defined in: notifications/src/messages/MailMessage.ts:258

Embed an image referenced from the HTML body as <img src="cid:the-id">, rather than listing it as a download.

Parameters

cid

string

attachment

Omit<MailAttachment, "cid" | "inline">

Returns

this

toPayload()

toPayload(defaultFrom, fallbackTo): MailPayload

Defined in: notifications/src/messages/MailMessage.ts:281

Resolve to the wire payload a driver sends. defaultFrom and fallbackTo come from MailChannel (config default sender + the notifiable's address).

Parameters