Transport protocols

The mail component provides transport protocols both for sending and retrieving mail. For sending mail we support:

• SMTP through the class ezMailSmtpTransport
• MTA through the class ezcMailMtaTransport

ezcMailSmtpTransport makes it possible to send mail over the SMTP protocol. If you prefer using a local mail agent you can use ezcMailMtaTransport which wraps over the PHP mail function..

For mail retrieval we currently support:

• POP3 through the class ezcMailPop3Transport

Send a mail with the composer

Sending a mail using the composer is very straightforward. This small example displays how to send a normal text message.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mail = new ezcMailComposer();
  5. $mail->from = new ezcMailAddress( 'sender@example.com', 'Adrian Ripburger' );
  6. $mail->addTo( new ezcMailAddress( 'receiver@example.com', 'Maureen Corley' ) );
  7. $mail->subject = "This is the subject of the example mail";
  8. $mail->plainText = "This is the body of the example mail.";
  9. 
 10. $mail->build();
 11. 
 12. $transport = new ezcMailMtaTransport();
 13. $transport->send( $mail );
 14. 
 15. ?>

Send a mail with HTML, inline images and attachments

An example with HTML text, images and attachments can be found in the ezcMailComposer class description.

Building a mail from scratch

The class structure of the mail component follows that of the mail MIME. This means that you can build advanced MIME messages part by part.

The first example displays how to build a similar message to the one above.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mail = new ezcMail();
  5. $mail->from = new ezcMailAddress( 'sender@example.com', 'Boston Low' );
  6. $mail->addTo( new ezcMailAddress( 'receiver@example.com', 'Maggie Robbins' ) );
  7. $mail->subject = "This is the subject of the example mail";
  8. $mail->body = new ezcMailText( "This is the body of the example mail." );
  9. 
 10. $transport = new ezcMailMtaTransport();
 11. $transport->send( $mail );
 12. 
 13. ?>

As you can see there is not much difference compared to the composer version. In the next example we will add an attachment to our manually built mail:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mail = new ezcMail();
  5. $mail->from = new ezcMailAddress( 'sender@example.com', 'Bernard Bernoulli' );
  6. $mail->addTo( new ezcMailAddress( 'receiver@example.com', 'Wendy' ) );
  7. $mail->subject = "This is the subject of the example mail";
  8. $textPart = new ezcMailText( "This is the body of the example mail." );
  9. $fileAttachment = new ezcMailFile( "~/myfile.jpg" );
 10. $mail->body = new ezcMailMultipartMixed( $textPart, $fileAttachment );
 11. 
 12. $transport = new ezcMailMtaTransport();
 13. $transport->send( $mail );
 14. 
 15. ?>

The file 'myfile.jpg' must of course exist in order for this example to work.

Extending the mail component

Even though the mail component supports a lot it does not support everything. There is no reason to dispair however, since it is very simple to extend. The following example shows how you can insert mail digests as attachments to your mail.

The mail system already supports sending attachments through the ezcMailMultipartMixed type. Unfortunately directly inserting an ezcMail object as a part does not work. This is because mail digests are a special case: they require two extra headers that are separated by the normal headers in the e-mail.

To make it work we will create the class RFC822Digest that adds these headers:

  1. <?php
  2. 
  3. class RFC822Digest extends ezcMailPart
  4. {
  5.     private $mail = null;
  6.     public function __construct( ezcMail $mail )
  7.     {
  8.         $this->mail = $mail;
  9.         $this->setHeader( 'Content-Type', 'message/rfc822' );
 10.         $this->setHeader( 'Content-Disposition', 'inline' );
 11.     }
 12. 
 13.     public function generateBody()
 14.     {
 15.         return $this->mail->generate();
 16.     }
 17. }
 18. 
 19. ?>

Our new class extends the ezcMailPart class. This is required for all parts of a mail. ezcMailPart provides two important methods that we can override: ezcMailPart::generateHeaders() and ezcMailPart::generateBody(). These two methods are called in succession by the parent part and should return the headers and the body text of the part. We don't need to override generateHeaders() since we can simply set the headers we want directly on the object. We do need to override generateBody() however, since we want to include the full text of the mail digest.

The new class can be used directly when building an email. The example assumes that a valid ezcMail object is available in the $digest variable.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mail = new ezcMail();
  5. $mail->from = new ezcMailAddress( 'sender@example.com', 'Largo LaGrande' );
  6. $mail->addTo( new ezcMailAddress( 'receiver@example.com', 'Wally B. Feed' ) );
  7. $mail->subject = "This is the subject of the mail with a mail digest.";
  8. $textPart = new ezcMailText( "This is the body of the mail with a mail digest." );
  9. 
 10. $mail->body = new ezcMailMultipartMixed( $textPart, new RFC822Digest( $digest ) );
 11. 
 12. $transport = new ezcMailMtaTransport();
 13. $transport->send( $mail );
 14. 
 15. ?>

Character encoding

Most of the world does not speak and write US ascii and require more advanced character encoding to display their mail correctly.

The following example shows how to send a mail entirely encoded with iso-8859-1:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mail = new ezcMail();
  5. $mail->from = new ezcMailAddress( 'sender@example.com', 'Norwegian characters: æøå', 'iso-8859-1' );
  6. $mail->addTo( new ezcMailAddress( 'reciever@example.com', 'More norwegian characters: æøå', 'iso-8859-1' ) );
  7. $mail->subject = 'Oslo ligger sør i Norge og har vært landets hovedstad i over 600 år.';
  8. $mail->subjectCharset = 'iso-8859-1';
  9. 
 10. $mail->body = new ezcMailText( 'Oslo be grunnlagt rundt 1048 av Harald Hardråde.', 'iso-8859-1' );
 11. 
 12. $transport = new ezcMailMtaTransport();
 13. $transport->send( $mail );
 14. 
 15. ?>

You can of course choose and combine any available character set. Make sure that the input text is in the encoding specified or you may get unexpected results.

Mail retrieval and parsing

Many applications have a need to interact with an email address. The mail component makes this easy through the class ezcMailParser and the mail retreival transport classes. Mail is fetched, parsed and returned to you in the same structure that is used to send mail.

The mail components currently allows you to fetch and parse mail messages from POP3, mbox files, single mail files and from variables. The parser fully supports mail in all character sets, multipart mail (attachments), HTML mail, HTML mail with images and digest messages.

The following example shows how to fetch all messages from a POP3 account and parse them for usage.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $pop3 = new ezcMailPop3Transport( "pop3.example.com" );
  5. $pop3->authenticate( "user", "password" );
  6. $set = $pop3->fetchAll();
  7. $parser = new ezcMailParser();
  8. $mail = $parser->parseMail( $set );
  9. ?>

The parser returns an array of ezcMail messages with parts organized as the MIME structure of the mail.

If the mail contains attachments they will be saved to disk in temporary files. If you want to keep the files they must be moved to a temporary place as shown in the next example.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $set = ezcMailFileSet( "path_to_the_mail_file" );
  5. $parser = new ezcMailParser();
  6. $mail = $parser->parseMail( $set );
  7. 
  8. // The mail is a simple mail with a text and a file attachment.
  9. // Hence the body is a ezcMailMultipartMixed object.
 10. $parts = $mail->body->getParts();
 11. 
 12. // the first part is the text message, the second is the file attachment
 13. $file = $parts[1];
 14. 
 15. // lets move the attachment
 16. $newPlacement = '/path/to/my/files/' . basename( $file->fileName );
 17. rename( $file->fileName, $newPlacement );
 18. 
 19. // if you still want to use the $file object remember to tell it that we changed the name
 20. $file->fileName = $newPlacement;
 21. ?>