Transport protocols

The mail component provides two different transport classes. ezcMailTransportSmtp makes it possible to send mail over the SMTP protocol. If you prefer using a local mail agent you can use ezcMailTransportMta which wraps over the PHP mail function..

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. include( "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 ezcMailTransportMta();
 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. include( "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 ezcMailTransportMta();
 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. include( "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 ezcMailTransportMta();
 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 to 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. include( "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 ezcMailTransportMta();
 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. include( "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 ezcMailTransportMta();
 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.