How to send e-mail using the Stanford Web Application Toolkit

From Web Services Wiki

Jump to: navigation, search

Contents

Problem

You'd like to securely send an e-mail message through your application with an optional list of file attachments.

Solution

Use the StanfordEmail class to securely send e-mail. A basic example is shown below.

A simple message

// Include StanfordEmail
include_once("stanford.email.php");
 
// Create a new StanfordEmail
$email = new StanfordEmail();
 
// Set sender ("From" address)
$email->set_sender("my_email@mydomain.tld", "My Name");
 
// Set recipient ("To" address)
$email->set_recipient("other_email@otherdomain.tld", "Other Person's Name");
 
// Set the subject
$email->set_subject("Hey, this is a test message");
 
// Set the body
//  If the body contains HTML, the second argument should be set to true.
//  If the body is plaintext, set the second argument to false
$email->set_body("<p><b>Hello!</b></p>", $is_html = true);

Adding multiple recipients, CCs, BCCs, and reply-to addresses

You may also send messages with multiple recipients, CCs, BCCs, and Reply-Tos.

// Add a couple of recipients
$email->add_recipient("other_email@otherdomain.tld", "Person's Name");
$email->add_recipient("another_email@anotherdomain.tld", "Abraham Lincoln");
 
// Add CCs, BCCs, and Reply-Tos
$email->add_cc("cc@domain.tld", "CC Person");
$email->add_bcc("bcc@domain.tld", "Michael Jordan");
$email->add_reply_to("my_other_address@mydomain.tld", "My Name");

File attachments

Additionally, you may attach files and put restrictions on the nature of files used as attachments.

// Set restrictions
$email->set_allowed_extensions("jpg", "jpeg", "gif", "png");    // Only allow certain types of images
$email->set_max_filesize(100000);                               // under 100 KB
 
// Add a file attachment
$email->add_attachment("picture.jpg");
 
// Add another attachment
$email->add_attachment("/path/to/image.gif");

Custom error messages

Though StanfordEmail does a great deal of error checking, your application may require additional checks. Use the method add_error_message to add your own custom error message to the list. An example is shown below.

// Set list of allowed e-mail addresses
$valid_emails = array("admin@mystanfordwebsite.com", "mail@mystanfordwebsite.com", "support@mystanfordwebsite.com");
 
// Check if sender's address is not in the list of allowed e-mails
if(in_array($email->get_sender_email(), $valid_emails) == false) {
 
  // Add a custom error message
  $email->add_error_message("Sorry, " . $email->get_sender_email() . " is not allowed.");
 
}

Sending the message and handling errors

Call the send function to try to send the message. If any errors occurred (whether they were detected automatically by StanfordForm or added manually using add_error_message), the message will not be sent and the function will return false. Call display_errors to output a simple HTML list or call get_errors to get the messages as an array.

// Try to send the message
if($email->send() == true) {
  echo "<p>Message sent successfully!</p>";
}
 
// Handle errors
else {
  // Display error message(s)
  $email->display_errors();
 
  // Alternatively, get the list of error messages and display them yourself
  $errors = $email->get_errors();
}

Discussion

Can I customize the output of display_errors?

Yes. Errors are displayed using the following template:

<div class='{error_css_class}'>
  <p>{error_heading}</p>
  <ul>
    <li>Error 1</li>
    <li>Error 2</li>
    <li>Error 3</li>
  </ul>
</div>

There are two functions you may use to customize the output: set_error_heading and set_error_css_class.

// Customize error output
$email->set_error_heading("Oops!  The following errors prevented your e-mail from being sent:");
$email->set_error_css_class("my_css_class");
 
// Display errors
$email->display_errors();

You may then use a stylesheet to customize colors, fonts, margins, etc.

What are the accessor methods for this class?

Get information about the StanfordEmail object using the following accessor methods:

$email->get_alt_body();     // Alt body (plaintext)
$email->get_bccs();         // BCCs
$email->get_body();         // Body
$email->get_ccs();          // CCs
$email->get_recipients();   // Recipients
$email->get_reply_tos();    // Reply-Tos
$email->get_sender_email(); // Sender's e-mail address
$email->get_sender_name();  // Sender's name
$email->get_subject();      // Subject

References

PHPMailer - StanfordEmail is based on the open source project PHPMailer

Personal tools