Ultimate E-mail Toolkit Documentation

The Ultimate E-mail Toolkit is an open source PHP library designed to handle all of your one-off e-mail needs on nearly all web hosts. This toolkit directly talks to SMTP and POP3 servers just as a regular e-mail client would instead of relying on the PHP mail() function. The result is a high level of reliability in delivery of e-mail messages to recipients. Functions like ConvertHTMLToText() and MakeValidEmailAddress() make it easy to do complex tasks such as convert ugly HTML input into a beautiful plain-text equivalent and analyze an e-mail address to automatically correct common mistakes. All of that while following the various IETF RFC Standards surrounding e-mail. The Ultimate E-mail Toolkit is extracted from Barebones CMS but does not depend on Barebones CMS to operate.

If you are thinking of using this toolkit for bulk e-mail, spam, or other abuse of people's trust, please be aware that the tradeoff for using this toolkit correctly is performance - it can only process low volumes of e-mail through the various routines. The correct use of this library is one-off e-mails that are triggered by the end-user having completed some action on your website. For example, registering for an account to access more features or purchasing a product in your e-commerce platform.

Features

The following is a short list of features found in the Ultimate E-mail Toolkit:

And much more!

License

The Ultimate E-mail Toolkit is extracted from Barebones CMS and the license is also your pick of MIT or LGPL. The license and restrictions are identical to the Barebones CMS License.

If you find the Ultimate E-mail Toolkit useful, financial donations are sincerely appreciated and go towards future development efforts.

Download

Ultimate E-mail Toolkit 1.0RC7 is the seventh release candidate of Ultimate E-mail Toolkit.

Download ultimate-email-1.0rc7.zip

If you find the Ultimate E-mail Toolkit useful, please donate toward future development efforts.

Installation

Installing the Ultimate E-mail Toolkit is easy. The installation procedure is as follows:

Installation is easy. Using the toolkit is a bit more difficult.

Upgrading

Like Barebones CMS, upgrading the Ultimate E-mail Toolkit is easy - just upload the new files to the server and overwrite existing files.

Sending E-mail/Address Validation

Two of the most popular things to do in response to user form submissions is to validate the user's e-mail address and send a one-off e-mail. E-mail is incredibly tricky to get right and you may be wondering why your e-mail doesn't get through spam filters. From a spam filter's perspective, a good e-mail is well-formed, is indistinguishable from one of the popular e-mail clients, comes from an IP address with a good reputation (i.e. NO mass e-mails), and has content the user wants to receive based on the history of the user. If it is a multipart e-mail, both the HTML and text versions need to look roughly the same. E-mail has a history of being abused, so it is inevitable that, no matter what you do, some e-mail will get blocked by spam filters. Using this toolkit gets my e-mails through more spam filters than anything else I've ever used.

Enough blabbing. How about an example? Let's start with everyone's favorite - the signup form:

<?php
	require_once "support/smtp.php";
	require_once "support/pop3.php";
	require_once "support/str_basics.php";

	Str::ProcessAllInput();

	// A good approach to form design is to send the submission
	// into the same form so the user can correct any errors.
	$message = "";
	if (isset($_REQUEST["name"]) && isset($_REQUEST["email"]))
	{
		// Check the name.
		$name = trim($_REQUEST["name"]);
		if ($name == "")  $message .= "<li>Please fill in your 'Name'.</li>";

		// Check the e-mail address.
		$email = trim($_REQUEST["email"]);
		if ($email == "")  $message .= "<li>Please fill in your 'E-mail Address'.</li>";
		else
		{
			$result = SMTP::MakeValidEmailAddress($_REQUEST["email"]);
			if (!$result["success"])  $message .= "<li>Invalid 'E-mail Address'.  " . htmlspecialchars($result["error"]) . "</li>";
			else if ($result["email"] != $email)  $message .= "<li>Invalid 'E-mail Address'.  Did you mean:  " . htmlspecialchars($result["email"]) . "</li>";
		}

		// If all information submitted is good (no errors),
		// then continue on.
		if ($message == "")
		{
			// Do some processing here
			// (e.g. insert rows into a database)...

			// Build the e-mail to send.
			// The easiest/laziest way to build the
			// body is to use PHP Heredoc syntax.
			$body =<<<EOF
<html>
<head>
<style type="text/css">
/* Inline CSS styles go here.  If any. */
</style>
</head>
<body>
{$name},<br />
<br />
Thank you for signing up for our awesome stuff!<br />
<br />
Get a great deal on one of our famous green plastic monkeys by using coupon code '123XYZ' in our online store with your next order.<br />
<br />
The staff at some-amazing-website.com.<br />
</body>
</html>
EOF;

			// Send the e-mail to the user.
			// Change the stuff in '[]' to your server settings.
			$smtpoptions = array(
				"headers" => SMTP::GetUserAgent("Thunderbird"),
				"htmlmessage" => $body,
				"textmessage" => SMTP::ConvertHTMLToText($body),
				"server" => "[smtp.yourhost.com]",
				"port" => [25 or 465],
				"secure" => [true or false],
				"username" => "[YOUR e-mail username]",
				"password" => "[YOUR e-mail password]"
			);

			$pop3options = array(
				"server" => "[pop3.yourhost.com]",
				"port" => [110 or 995],
				"secure" => [true or false]
			);

			$fromaddr = "[YOUR e-mail address]";
			$subject = "Thanks for signing up!";
			$result = SMTP::SendEmail($fromaddr, $email, $subject, $smtpoptions);
			if (!$result["success"])
			{
				// This is usually the correct thing
				// to do to implement POP-before-SMTP.
				if ($smtpoptions["username"] != "" && $smtpoptions["password"] != "")
				{
					$pop3 = new POP3;
					$result = $pop3->Connect($smtpoptions["username"], $smtpoptions["password"], $pop3options);
					if ($result["success"])
					{
						$pop3->Disconnect();

						$result = SMTP::SendEmail($reportinfo["from"], $toaddr, $subject, $smtpoptions);
					}
				}

				if (!$result["success"])
				{
					// Failed to send.
				}
			}

			// Forward the user to a thank you page so
			// they can't hit reload and repeat the above.
			header("Location: http://somewebsite.com/someform/?thanks=1");
			exit();
		}
	}
	else if (isset($_REQUEST["thanks"]))
	{
?>
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Sign up!</title>
<link rel="stylesheet" href="main.css" type="text/css" media="all" />
</head>
<body>
<div class="maincontent">
<h1>Best signup form EVER!</h1>

<p>Thank you for signing up with us.  An e-mail has been sent to you containing a coupon code for our best-selling product as our way of saying thanks!</p>

</div>
</body>
</html>
<?php

		exit();
	}

	if (!isset($_REQUEST["name"]))  $_REQUEST["name"] = "";
	if (!isset($_REQUEST["email"]))  $_REQUEST["email"] = "";
?>
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Sign up!</title>
<link rel="stylesheet" href="main.css" type="text/css" media="all" />
</head>
<body>
<div class="maincontent">
<h1>Best signup form EVER!</h1>

<p>This quick-n-dirty web form lets you sign up for something.</p>

<form class="signup" action="index.php" method="post">
<?php
	if ($message != "")
	{
?>
<div class="formerror">
	Please correct the following errors:<br />
	<ul><?php echo $message; ?></ul>
</div>
<?php
	}
?>

<div class="formitem">
	<div class="formitemtitle">Name</div>
	<input class="text" type="text" name="name" value="<?php echo htmlspecialchars($_REQUEST["name"]); ?>" />
	<div class="formitemdesc">Your first and last name.</div>
</div>

<div class="formitem">
	<div class="formitemtitle">E-mail Address</div>
	<input class="text" type="text" name="email" value="<?php echo htmlspecialchars($_REQUEST["email"]); ?>" />
	<div class="formitemdesc">Your e-mail address so we can send you the goods.</div>
</div>

<div class="formsubmit">
	<input type="submit" name="submit" value="Signup" />
</div>
</form>
</div>
</body>
</html>

The above is what I consider to be a fairly boilerplate form and response page. Hopefully it is commented well enough to get the overall idea. The initial form shows up at the bottom of the code and the processing logic, including building and sending the e-mail, shows up at the top. The code assumes this is a POP-before-SMTP host for sending e-mail, which isn't a bad thing to assume as a lot of e-mail providers have setups like this. Since the toolkit, by default, doesn't use the PHP mail() function, it requires e-mail credentials to log into a SMTP or POP3 host. The goal is to look and act exactly like a real e-mail client. In the above case, some flavor of Thunderbird is attempting to be emulated.

There are a lot of options not being used. See the SMTP and POP3 classes for in-depth documentation.

Retrieving E-mail

The included POP3 library makes it possible to create a webmail gateway or do automation. In this day and age of GMail and other AJAX-driven e-mail hosts, users may hate you if you build a webmail gateway. However, privacy is a pretty good reason someone would choose to build their own webmail gateway today.

Automation via cron (or WebCron) is generally the more attractive reason to use the full POP3 library. You could set up a special e-mail account that receives e-mail and then you use the POP3 library in a script to retrieve and process the incoming e-mails to do something cool. For example, the ability to retrieve bounce e-mails with the POP3 library allows a web application to potentially let the user know that the system failed to send a message to them when they signed up for a service and why the message bounced.

Without further ado, here is a basic example of connecting to a POP3 server and retrieving all the messages:

<?php
	// Since POP3 retrieval takes a while,
	// it is best to run this via 'cron'.
	require_once "support/pop3.php";
	require_once "support/mime_parser.php";

	// Change the stuff in '[]' to your server settings.
	$pop3options = array(
		"server" => "[pop3.yourhost.com]",
		"port" => [110 or 995],
		"secure" => [true or false]
	);

	$pop3 = new POP3;
	$result = $pop3->Connect("[YOUR e-mail username]", "[YOUR e-mail password]", $pop3options);
	if (!$result["success"])  echo "POP3 - Connect():  " . $result["error"] . "\n";
	else
	{
		$result = $pop3->GetMessageList();
		if (!$result["success"])  echo "POP3 - GetMessageList():  " . $result["error"] . "\n";
		else
		{
			$ids = $result["ids"];
			foreach ($ids as $id)
			{
				$result = $pop3->GetNextMessage($id);
				if (!$result["success"])  echo "POP3 - GetNextMessage():  " . $result["error"] . "\n";
				else
				{
					$message = $result["message"];

					// Process $message here with MIMEParser::Parse(), etc.

					$result = $pop3->DeleteMessage($id);
					if (!$result["success"])  echo "POP3 - DeleteMessage():  " . $result["error"] . "\n";
				}
			}
		}

		$pop3->Disconnect();
	}
?>

There are a number of options and some key functions not being used (e.g. MIMEParser::Parse() is mentioned above but not used). See the POP3 and MIME Parser classes for in-depth documentation.

© CubicleSoft