{mail:condition:to:subject:body:lang:from:reply_to:errors_to:sender:cc:bcc:attachments}

Description

Sends an e-mail when the first parameter (condition) is true. WARNING: this runs on every page render, so it can send mail on every page load - guard it with a condition. The command does nothing (returns an empty string) when condition is empty or 0, or when body is empty. Recipients (to) may be one e-mail, a JSON array of e-mails, or item ids of Reader records in slices related to the current site (matched by their e-mail field). Mail is always sent as HTML. cc and bcc are filtered to valid e-mails. from accepts a plain address or a Name address form. attachments is one URL, a JSON array of URLs, or a JSON object mapping display names to URLs. On success it returns the number of recipients queued; the first two mails per request are sent immediately and the rest are deferred. Source: AA_Stringexpand_Mail in stringexpand.php.

Parameters

condition required

Whether to send. The mail is sent only when this is true (non-empty and not 0). Use it as a guard so the command does not fire on every page load - e.g. a flag, a {qss:} value, or an {ifin:} test. Empty or 0 means do nothing and return an empty string.

to required

Recipient(s). One e-mail (jane@example.org), a JSON array of e-mails, or item ids of Reader records (separated by space or dash) in slices related to the current site; ids are matched to readers by their e-mail field. If the value contains an at sign it is treated as e-mail(s), otherwise as Reader ids.

subject optional

The e-mail subject line.

body required

The message body, sent as HTML. Often a rendered {view:} or {item:} so the e-mail reuses a template. Required - an empty body sends nothing.

lang optional

Language/charset for the message, e.g. utf-8. Controls encoding and localized mail parts.

from optional

Sender address shown in the From header. A plain address like actionapps@ecn.cz, or a display-name form written as the name followed by the address in angle brackets (ActionApps then actionapps@ecn.cz).

reply_to optional

Reply-To address. Replies go here instead of the From address.

errors_to optional

Errors-To address. Bounce and delivery-error notices are sent here.

sender optional

Sender header (the envelope/agent sending the mail), distinct from from.

cc optional

Carbon-copy recipient(s): one e-mail or a JSON array. Invalid addresses are dropped.

bcc optional

Blind-carbon-copy recipient(s): one e-mail or a JSON array. Invalid addresses are dropped.

attachments optional

File attachment(s) by URL. One URL as a string, a JSON array of URLs, or a JSON object mapping display names to URLs to rename the attached files. Escape any colon in a URL as http#:// inside the parameter.

Examples

virtual{mail:0:jane@example.org:Monthly report:The report is ready.:utf-8:news@example.org::::cc@example.org:bcc@example.org}

Expected(no-op here; with a true condition, copies cc@example.org and blind-copies bcc@example.org)

cc is the 10th parameter and bcc the 11th, so the empty colons skip reply_to, errors_to, and sender. Both cc and bcc accept one address or a JSON array; invalid addresses are dropped.

virtual

{mail:0:jane@example.org:Photos:See the attached images.:utf-8:news@example.org::::::["http#://example.org/a.png","http#://example.org/b.png"]}

Expected(no-op here; with a true condition, attaches a.png and b.png from their URLs)

attachments (the 12th parameter) is one URL, a JSON array of URLs, or a JSON object mapping names to URLs. Escape the colon in each URL as http#:// so the parameter parser does not split on it. The six empty colons skip from through bcc.

virtual{mail:0:jane@example.org:Newsletter:{view:24}:utf-8:news@example.org}

Expected(no-op here; with a true condition, queues one HTML mail whose body is the output of view 24)

body is usually a rendered template. Here the message body is the HTML produced by view 24, so the e-mail reuses an existing view layout.

virtual{mail:0:jane@example.org:Your question:See our note below.:utf-8:Helpdesk <help@example.org>:replies@example.org}

Expected(no-op here; with a true condition, From shows Helpdesk and replies go to replies@example.org)

from accepts a display-name form Name <address>. reply_to (the 7th parameter) sets where replies are routed, separate from the From address.

virtual{mail:{qss:notify}:jane@example.org:Hello:Welcome aboard.:utf-8:noreply@example.org}

Expected(empty unless the notify query parameter is present; then returns 1)

condition is any expression. Here the mail only goes out when the page URL carries notify (via {qss:notify}). This is how you stop the command firing on every page load.

virtual{mail:0:["anna@example.org","ben@example.org"]:Notice:Please read the update.:utf-8:news@example.org}

Expected(no-op here; with a true condition, queues 2 mails - one per address - and returns 2)

to may be a JSON array of e-mails. Each gets its own message; the return value is the number of recipients queued. The first two per request are sent immediately, the rest deferred.

virtual{mail:0:jane@example.org:Account ready:Your account is now set up.:utf-8:noreply@example.org}

Expected(no-op here: condition is 0; with a true condition this queues one HTML mail to jane@example.org and returns 1)

The shape of a basic send: condition, to, subject, body, lang, from. The leading 0 is the guard - this example sends nothing on render. Replace it with a real test to send. body is sent as HTML.

virtual{mail:0:7847785-435636-244355:Members update:News for members.:utf-8:news@example.org}

Expected(no-op here; with a true condition, sends to the Reader records with those ids whose slice is related to the current site)

When to has no at sign it is read as item ids (dash- or space-separated) of Reader records. Only ids in slices related to the current site are kept, and each is addressed by its e-mail field. A silently created template carries the body.

← All expressions