For more information... RTFM!
NAVIGATION
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

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 Link to an external page Perl module.

Note

Note

If SendMailProgram is set to "none" then your email will not be sent, and an error will be logged to the website's error log file.

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 Link to an external page 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

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

Note

This parameter requires that the MIME::Lite Link to an external page Perl module is installed and operational.

Availability

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

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

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

Note

This parameter requires that the MIME::Lite Link to an external page Perl module is installed and operational.

Availability

Availability

This parameter was introduced in version 5.4.0, and is therefore not available for use with any earlier Interchange version.

Category:  Interchange tags
Last modified by: Kevin Walsh
Modification date: Friday 4 May 2007 at 9:28 AM (CDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us