Mail

mash.mail · Communications

Limited on SaaS

• On SaaS, mail goes through the managed transport and only to members of the tenant. Use mail.client(dsn) to send elsewhere.

mash.mail sends email from a script: a one-line notification, a message with attachments, or a message built from one of Foldr’s notification templates. It sends through the mail setup Foldr already has, so there’s no server to configure in the script.

How it works

Three ways to send. send(recipient, subject, body) is the quick one. message({...}) builds a message object you fill in step by step and send with sendMessage. sendWithTemplate(template, recipient, subject, data) renders a notification template (by name, id or UUID) with your data first. templates() lists the ones you can use.

Recipients are flexible. A recipient can be an address, a User, a Group or a list mixing them. A group is delivered as one message with its members on blind copy, up to 500 addresses. Pass cc, bcc and replyTo the same way.

Attachments are Files. Pass one File or a list of Files, not paths. A folder is refused. A file Governance blocks from leaving the organisation is refused.

On SaaS you can only email people who have an account. An address outside your Foldr stops the run with a message saying so. On an appliance there’s no such limit. To send somewhere else, mash.mail.client(dsn) makes a client for an SMTP server you name.

No mail set up is an error. On an appliance with no mail server configured the call stops the run and says where an administrator sets it up (Settings > Integrations > Mail).

delay queues the send instead of sending now.

Common tasks

Send a short note to the person who triggered the script:

set who to mash.event.user
mash.mail.send(who, "Your invoice was filed", "INV-2041 is now in Finance > Invoices.")

Build a message with an attachment and a copy:

set doc to mash.files.get("Finance", "Invoices/2026/INV-2041.pdf")
set note to mash.mail.message({
    recipient: "accounts@example.com",
    cc: [mash.user()],
    subject: "Invoice INV-2041",
    body: "Attached for your records.",
    attachments: doc
})
mash.mail.sendMessage(note)

Fill a notification template:

mash.mail.sendWithTemplate(
    "Order confirmation",
    "buyer@example.com",
    "Your order SO-20417",
    {ref: "SO-20417", total: "£120.00"}
)

Mail a whole group:

mash.mail.send(mash.group("Finance"), "Month end", "The ledger closes tomorrow.")

Watch out for

• A recipient the guard refuses stops the whole run, and an error block doesn’t catch it. Check addresses before you send if some may be outside your Foldr.
• A failure from the mail server is recorded and the script carries on. Put an error block after the send if the next step depends on it.
• A script that is run twice sends twice. Record that you’ve sent (a custom field is a good place) and check it first.
• A template that doesn’t exist stops the run. The message names the template it couldn’t find.

See also

Talking to the outside world, mash.users and mash.groups for finding recipients.

Send messages via email

Methods

client

mail.client(dsn: string) → Client

Create an SMTP client from a DSN string. The DSN’s host is checked the way mash.http checks a URL: no internal or reserved address unless an administrator allowed it.

message

mail.message(options?: array = []) → Message

Create a new email message.

parser

mail.parser(file: File)

Parse an email file (EML/MIME)

send

mail.send(recipient: mixed, subject: mixed, body: mixed, attachments?: mixed = [], cc?: mixed = [], bcc?: mixed = [], replyTo?: mixed = [], delay?: mixed)

Send an email to a recipient

sendMessage

mail.sendMessage(message: Message, delay?: int)

Send a prepared Message object

sendWithTemplate

mail.sendWithTemplate(template: mixed, recipient: mixed, subject: string, data: array, attachments?: mixed = [], cc?: mixed = [], bcc?: mixed = [], replyTo?: mixed = [], delay?: mixed)

Send an email using a notification template (by name, ID, or UUID)

template

mail.template(template: mixed) → TemplateModel

Get a notification template by name, ID, or UUID.

templates

mail.templates() → TemplateModel[]

List this tenant’s notification templates.