CGIs : MT-Mail-Entry 2.0 Jun 23 2003 | # | C:37

MT-Mail-Entry 2.0

June 23, 2003 - updated February 8, 2006 (Download)

MovableType comes with an mt-send-entry.cgi that allows your readers to email a link to an entry. Often, you might prefer to send a user the actual entry (or an excerpt) instead of just a link.

The mt-mail-entry.cgi allows you to specify the templates that are used to create the email message. The email may be sent using plain text, HTML, or both formats. When an email is sent, the entry ID, sender and recipient are logged in the activity log.

Installation

Place the mt-mail-entry.cgi in the same directory as the mt.cgi and change the permissions to 755.

Creating a Mail Template

Go to your blog’s template section and create a “mail_entry_text” (for plain text email) and/or “mail_entry_html” (for HTML email) template. It is recommended that you specify both templates to support text- as well as HTML-based applications. You may choose to use another name for the templates, in which case you also have to specify the template name(s) in “template_text” and “template_html” parameters when calling the mt-mail-entry.cgi.

You may use the same tags that are valid in an Individual Archive Template. You may also use one of the following additional tags:

  • MTMailEntryVersion

    Represents the version of this CGI.
  • MTMailTo

    Represents the email address that the entry is being sent to.
  • MTMailFrom

    Represents the email address that the entry is being sent from.
  • MTMailMessage

    Represents the optional message entered by the person sending the entry.
  • MTMailIfMessage

    Conditional tag that is true if the sender has entered text into the message box.
  • MTMailIfNoMessage

    Conditional tag that is true if the sender has not entered any text into the message box.

The mail_entry_text template should not contain any HTML tags (you may want to use the remove_html filter for that). A simple text template might look as follows:

<br />
<MTMailFrom> has sent you a link!<br />
 <br />
<MTMailMessage><br />
 <br />
Title: <MTEntryTitle><br />
Link: <MTEntryPermalink><br />
 <br />
<MTEntryBody remove_html="1"><br />

The mail_entry_html template should be a valid HTML document, similar to the Individual Entry Archive. Make sure you sanitize all user supplied information (i.e. <$MTMailMessage sanitize=”1”$>). You should explicitly specify a base URL or make sure that any links (to other documents, style sheets or images) are absolute — they should begin with http:// — so that they display correctly in the recipients mail application. An HTML template (specifying the entry’s permalink as its base URL) might look as follows:

<br />
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"<br />
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><br />
<html xmlns="http://www.w3.org/1999/xhtml"><br />
<head><br />
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><br />
<title><$MTBlogName$>: <$MTEntryTitle$></title><br />
<base href="<$MTEntryPermalink$>"><br />
<link rel="stylesheet" href="<$MTBlogURL$>styles-site.css" type="text/css" /><br />
</head><br />
 <body><br />
<div id="banner"><br />
<h1><a href="<$MTBlogURL$>" accesskey="1"><$MTBlogName$></a></h1><br />
<span class="description"><$MTBlogDescription$></span><br />
</div><br />
<div id="container"><br />
<div class="blog"><br />
<MTMailIfMessage><br />
<div class="blogbody"><br />
<p>Message from <<MTMailFrom remove_html="1" encode_html="1">></p><br />
<p><MTMailMessage sanitize="1"></p><br />
</div><br />
</MTMailIfMessage><br />
<div class="blogbody"><br />
<h3 class="title"><$MTEntryTitle$></h3><br />
<$MTEntryBody$><br />
<MTEntryIfExtended><br />
<span class="extended"><br />
<a href="<$MTEntryPermalink$>">Continue reading "<$MTEntryTitle$>"</a><br />
</span><br /><br />
</MTEntryIfExtended><br />
</div><br />
</div><br />
</body><br />
</html><br />

Adding a link to the Mail Form

Use the following template code to link to the mail entry form:

<br />
<a href="<$MTCGIPath$>mt-mail-entry.cgi?entry_id=<$MTEntryID$>">Email Entry</a><br />

If you want the email form to open in a popup window, add the following section to the top of your page:

<br />
<script type="text/javascript" language="javascript"><br />
<!--<br />
function OpenEmail (c) {<br />
    window.open(c,<br />
        'email',<br />
        'width=480,height=480,scrollbars=yes,status=yes');<br />
}<br />
//--><br />
</script><br />

and change the link to:

<br />
<a href="<$MTCGIPath$>mt-mail-entry.cgi?entry_id=<$MTEntryID$>"<br />
    onclick="OpenEmail(this.href); return false">Mail Entry</a><br />

Specifying a custom Mail Form

To customize the Mail Form, go to your blog’s template section and create a “mail_entry_form” template. You may choose to use another name for this template, in which case you also have to specify the template name in a “template_form” parameters when calling the mt-mail-entry.cgi.

You may use the same tags that are valid in the email template. You may also use one of the following additional tags to report errors in your email form:

  • MTMailIfEmailSent

    Conditional tag that is true if email was successfully sent.
  • MTMailIfNoEmailSent

    Conditional tag that is true if no email was sent.
  • MTMailIfErrors

    Conditional tag that is true if there were errors when submitting the form.
  • MTMailIfNoErrors

    Conditional tag that is true if there were no errors when submitting the form.
  • MTMailIfErrorFrom

    Conditional tag that is true if the sender address is incorrect.
  • MTMailIfNoErrorFrom

    Conditional tag that is true if the sender address is correct.
  • MTMailIfErrorTo

    Conditional tag that is true if the sender address is incorrect.
  • MTMailIfNoErrorTo

    Conditional tag that is true if the sender address is correct.
  • MTMailIfErrorSend

    Conditional tag that is true if errors were encountered while sending the email.
  • MTMailIfNoErrorSend

    Conditional tag that is true if no errors were encountered while sending the email.
  • MTMailIfNoErrorSend

    Conditional tag that is true if no errors were encountered while sending the email.
  • MTMailSendError

    The error reported by the system when sending the email. An empty string if there were no errros.

Default Mail Form

The default mail form looks like this:

<br />
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"<br />
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><br />
 <br />
<html xmlns="http://www.w3.org/1999/xhtml"><br />
<head><br />
<meta http-equiv="Content-Type" content="text/html; charset=<$MTPublishCharset$>" /><br />
<title><$MTBlogName$>: Email <$MTEntryTitle remove_html="1"$></title><br />
<link rel="stylesheet" href="<$MTBlogURL$>styles-site.css" type="text/css" /><br />
</head><br />
 <br />
<body><br />
<div id="banner-commentspop"><br />
<$MTBlogName$><br />
</div><br />
 <br />
<div class="blog"><br />
 <br />
<div class="comments-head">Send via email: <$MTEntryTitle$></div><br />
 <br />
<MTMailIfEmailSent><br />
<!-- If email was sent, let the user know --><br />
<div class="comments-body"><br />
The email <b><MTMailSubject></b> was successfully sent to <<MTMailTo encode_html="1">>.<br />
</div><br />
</MTMailIfEmailSent><br />
 <br />
<MTMailIfErrors><br />
<!-- If there were problems, let the user know --><br />
<div class="comments-body"><br />
<MTMailIfErrorFrom><br />
Your email address is not valid!<br />
</MTMailIfErrorFrom><br />
<MTMailIfErrorTo><br />
The recipient email address is not valid!<br />
</MTMailIfErrorTo><br />
<MTMailIfErrorSend><br />
Failed to send email: <MTMailSendError encode_html="1"><br />
</MTMailIfErrorSend><br />
</div><br />
</MTMailIfErrors><br />
 <br />
<div class="comments-body"><br />
<form method="get" action="<$MTCGIPath$>mt-mail-entry.cgi" name="mail_form"><br />
<input type="hidden" name="entry_id" value="<$MTEntryID$>" /><br />
 <br />
<table><br />
<tr><br />
<td><br />
    <label for="to">Recipient email address:</label><br /><br />
    <input tabindex="1" id="to" name="to" value="<MTMailTo encode_xml="1">" /><br /><br /><br />
</td><br />
<td><br />
    <label for="from">Your email address:</label><br /><br />
    <input tabindex="2" id="from" name="from" value="<MTMailFrom encode_xml="1">" /><br /><br /><br />
</td><br />
</tr><br />
</table><br />
 <br />
<label for="message">Message (optional):</label><br /><br />
<textarea tabindex="4" id="message" name="message"<br />
    rows="5" cols="50"><MTMailMessage encode_html="1"></textarea><br /><br /><br />
 <br />
<input type="button" onclick="window.close()" value=" Cancel " /><br />
<input style="font-weight: bold;" type="submit" name="post" value=" Send " /><br /><br /><br />
</form><br />
</div><br />
 <br />
</div><br />
 <br />
</body><br />
</html><br />

CGI Parameters

The following is the full list of parameters used by the mt-mail-entry.cgi:

  • entry_id (required)

    Specifies the ID of the entry that is being emailed.
  • template_text

    Specifies the name of the template used to create the plain-text mail message. The default template_text is “mail_entry_text”.
  • template_html

    Specifies the name of the template used to create the HTML mail message. The default template_html is “mail_entry_html”.
  • template_form

    Specifies the name of the template used to create the mail entry form. The default template_form is “mail_entry_form”.
  • from

    Specifies the sender address of the email.
  • to

    Specifies the recipient address of the email.
  • message

    Specifies the optional message of the email.
  • subject

    Specifies the subject of the email. The default subject is “<$MTBlogName$>: <$MTEntryTitle$>”.
  • post

    Specifies that the email form is being submitted.

If you need more flexibility (such as mailing additional fields, etc.), you may want to take a look at the MTCgi plugin.

Version History

  • Version 2.0 September 3, 2003

    Added support for (popup) form.
  • Version 1.1 July 7, 2003

    Added “require MT::Template”.
  • Version 1.0 June 23, 2003

    Original release.
The site database appears to be down.