Mail

Introduction

The Zoop Mail component is a powerful tool usable to send emails from within php. It supports templates (yes the same templates as gui). It also has a modular mailing engine and supports SMTP (authenticated or non authenticated) and sendmail.

WARNING: Zoop Mail uses a number of pear libraries to work with the smtp server, authentication, mail setup and socket connecting. We recommend if you use this component that you use the Zoop Lib package and install it in your zoop_dir/lib. We even recommend this over using your own systems pear packages because the stable mail_mime package is broken and hasn't been updated in nearly a year. We package the cvs one and it works quite well.

Configuration

The Mail component follows Zoops standard config format. The config file can be found in the app_dir/config/mail.php
Here is a list of the important directives in that file

define("mail_type", "smtp");
define("mail_smtp_host", "mail.yourserver.com");
define("mail_smtp_port", 25);
define("mail_smtp_auth_use", false);
define("mail_smtp_auth_username", "");
define("mail_smtp_auth_password", "");
 
define("gui_messages", "messages");

Most should be self explanatory, but please take note that the default settings may not work at all on your system and will likely need to be configured.

mail_type can be smtp or sendmail.
gui_messages is the directory inside of app_dir/templates/default/ that will contain your email templates.

Template Based Emails

We will begin by creating a template file in gui_messages as defined in our config file. For our purposes we will call the file notify.tpl and place the following contents into it:

{$message}
<br>
<hr>
The above message was sent by {$from} using 
our new Zoop based emailer!

We should now modify our postSend function that we have created to send this email from. The postSend function will look like:

function postSend($inPath)
{
	$post = getRawPost();
	$message = new message();
	$message->assign("message", $post['message']);
	$message->assign("from", $post['from']);
 
	$message->display(
		$post['from'], 
		$post['to'], 
		"", 
		$post['subject'], 
		"notify.tpl", 
		"multipart");
 
/*	$message->send(
		$post['from'], 
		$post['to'], 
		"", 
		$post['subject'], 
		"notify.tpl", 
		"multipart");
*/
}

Now to explain what it is doing.
We need to instantiate a new instance of message and assign it the variable we will be using. This works just like the gui object does.

The message object has a very nice function for development, the display function. It takes the same parameters at the send function, but instead of sending the email, it renders it and displays it to the browser. This enables us to create our email and preview it without sending a lot of emails in the process.

The send and the display functions take the following parameters (from, to, cc, subject, template, type).

A discussion on types

There are three types of emails ( text, html and multipart ). Text sends a plain text email that is readable by all email readers. The zoop mail component will automatically convert any html formatting to plain text if you use this option. The html type sends an html email that is readable by most email readers and can have much richer formatting than the plain text one. Multipart is a special type that sends out an email that contains both a plain text part and a html part and lets the email reader decide which one to display. This one should be fairly universally supported. It's major downside is that the byte size of the email is approximately double the others, since it sends the content of both text and html.

Using Mail to send Emails

Once the email is to our liking we simply switch the function call from display to send, cross our fingers and hope for the best. Obviously we should send an email to ourselves first (at an external email address) and make sure that everything is working properly with our connection to either the smtp server or the server's sendmail program.

SMTP vs Sendmail

When sending mail from a PHP script, you have two general choices, the UNIX "sendmail" function, and a SMTP server.

Sendmail is what PHP uses by default. This is primarily due to the fact that php does not have built in support for connecting to an SMTP server. When you use sendmail from a web server, the server itself attempts to deliver the mail by connecting to the destination system using the SMTP protocol.

SMTP stands for Simple Mail Transfer Protocol. Using this option permits you to connect to a local or remote SMTP server using a socket based connection. This is usually a more efficient means of sending email since it has less overhead then sendmail.