email
Generate and send email with the option of adding attachments.
Summary
- [email to subject reply from extra]
| Parameter
|
Description
|
Default
|
| to |
Valid email address(es) of the recipient(s).
This parameter is required. |
None |
| from |
Email address identifying the sender of the message. |
First MailOrderTo address |
| subject |
Short text describing the content of the message. |
<no subject> |
| reply |
Email address to be used in the "Reply-to:" SMTP header. |
None |
| extra |
Extra SMTP headers to be included in the email. |
None |
| attach |
Attach files or data to this email. |
None |
| hide |
Hide this tag's return code
|
No
|
| html |
Create a "multipart/alternate" email, with "text/plain" and "text/html" parts. |
None |
| interpolate |
Parse Interchange tags, included in the body text, before this container tag executes. |
Yes
|
Examples
Tag usage example
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
reply="foobar@example.com"
subject="Hello Kevin"
extra=|
X-Mailer: @@MV_PAGE@@
X-Session-ID: [data session id]
|]
Hello Kevin.
Stop slacking and create more docs!
[/email]
|
Perl example
$Tag->email({
to => 'Kevin Walsh <kevin@cursor.biz>',
from => 'Foobar <foobar@example.com>',
reply => 'foobar@example.com',
subject => 'Hello Kevin',
extra => "X-Mailer: @@MV_PAGE@@\nX-Session-ID: $Session->{id}",
body => "Hello Kevin.\n\nStop slacking and create more docs!\n",
});
|
or similarly with positional parameters:
|
$Tag->email($to, $subject, $reply, $from, $extra, $attribute_hash_reference, $body);
|
Description
This tag generates and sends an email article,
and sends it out via the method specified with the
SendMailProgram configuration directive.
The SendMailProgram should either be set up to
send mail via a Sendmail-style executable,
should (preferably) be set up to make use of the
Net::SMTP 
Perl module.
The email (SMTP) headers are generated using the parameters passed to
this tag.
The only required parameter is "to",
which is used to specify the destination address for the email.
The
All of the other parameters have reasonable defaults,
as listed below:
If the MIME::Lite Perl module is installed
and operational then email attachments may be specified using this
tag's "attach" and "html" parameters.
Don't use this facility to send spam or we'll come and get you.
Parameters
to
The recipient's email address, which can be specified either as a
simple email address
(i.e. "kevin@cursor.biz"),
or as a name and an email address
(i.e. "Kevin Walsh <kevin@cursor.biz>").
|
Note
This parameter is required.
The email cannot be sent if it is not addressed to at least
one recipient.
|
from
Email address identifying the sender of the message.
Just as with the "to" address, this address can be
specified either as a simple email address
(i.e. "kevin@cursor.biz"),
or as a name and an email address
(i.e. "Kevin Walsh <kevin@cursor.biz>").
If this parameter is not supplied then the first email address set up
using the MailOrderTo local configuration
directive will be used.
subject
Short text describing the content of the message.
The string "<no subject>" will be used if this
parameter is not supplied.
reply
Email address to be used in the "Reply-to:" SMTP header.
No "Reply-to:" header line will be present if this parameter
is not supplied.
extra
Extra SMTP headers to be included in the email.
If multiple "extra" header lines need to be specified then
they must be separated using an ASCII LF (\n) character.
There must be no white space at the start of any of the "extra" header lines.
See the tag usage example,
above.
attach
This parameter allows you to create a "multipart/mixed" email,
with whatever attachments you need.
The MIME content type and disposition of the parts will be automatically
set for you,
unless you specify otherwise,
and a valid multipart email will be sent.
|
|
Note
This parameter requires that the MIME::Lite Perl module is
installed and operational.
|
|
Availability
This parameter was introduced in version 5.4.0,
and is therefore not available for use with any earlier Interchange version.
|
To add a single file as an attachment
The "attach" parameter can be used as follows:
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
subject="Email with an attachment"
attach="images/foo.gif"
]This email has an attachment.[/email]
|
To attach multiple files to the email
Multiple "attach" parameters can be specified
as follows:
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
subject="Email with an attachment"
attach.0="images/foo.gif"
attach.1="images/bar.gif"
]This email has two attachments.[/email]
|
|
|
Note
Interchange does not impose a limit on the number of attachments
that can be specified in this way.
The limit will be determined by the size of the attachments and
the amount of memory and swap space available on your server.
You probably shouldn't attach multi-gigabyte ISO images to
your emails.
|
For more control over the attachments
Each "attach" parameter can be specified as a Perl hash,
as follows:
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
subject="Email with two attachments"
attach.0=`{
type => 'image/gif',
path => 'images/foo.gif',
}`
attach.1=`{
type => 'image/jpeg',
data => $Tag->file('images/foo.jpeg') || $Tag->file('images/broken.jpg'),
filename => 'attachment_name.jpg',
}`
]This email has two attachments.[/email]
|
The "attach" parameter can also be specified as a Perl array,
as follows:
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
subject="Email with two attachments"
attach=`[
{
type => 'image/gif',
path => 'images/foo.gif',
filename => 'different_name.gif',
},
{
type => 'image/jpeg',
data => $Tag->file('images/foo.jpeg') || $Tag->file('images/broken.jpg'),
filename => 'attachment_name.jpg',
},
]`
]This email has two attachments.[/email]
|
Both of the above examples also show that the "data" hash key
can be used to attach arbitrary data to the email.
|
Warning
The "type" key must match the "data" content to
give the attachment some chance of being handled correctly by the
email recipient(s).
|
hide
This tag normally returns a true value if the email was sent,
and a false value otherwise.
If this parameter is true then no value will be returned.
html
This parameter allows you to create a "multipart/alternate" email,
with "text/plain" and "text/html" parts.
The MIME content type and disposition of the parts will be automatically
set for you, and a valid text-and-HTML email will be sent.
The "text/plain" part goes into the tag body, as usual.
The "text/html" part is gathered from the "html" parameter's value.
For example:
[email
to="Kevin Walsh <kevin@cursor.biz>"
from="Foobar <foobar@example.com>"
subject="Multipart email"
html="[scratchd eeew_nasty_html_part_in_here]"
]This is the nice plain text part.[/email]
|
|
|
Note
This parameter requires that the MIME::Lite
Perl module is installed and operational.
|
|
|
Availability
This parameter was introduced in version 5.4.0,
and is therefore not available for use with any earlier Interchange version.
|
