Path

ez components / documentation / api reference / 2007.1.1 / mail


eZ Components 2007.1.1

Mail

[ Tutorial ] [ Display example ] [ Mail listing example ] [ Rfcs ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Introduction

The Mail component provides functionality to send, retrieve and parse mail messages. If you require an easy way to send a mail, use the ezcMailComposer class, which allows you to send HTML mails with images, attachments and an optional text part. If you require more advanced mail messages, you can build the complete message yourself using the ezcMailPart derived classes. You can retrieve mail messages from different sources using the supported transports.

Class overview

This section gives you an overview of the main classes in the Mail component.

ezcMailComposer
This is a convenience class that allows you to send plain text or HTML messages with attachments, without having to construct the parts of the message yourself. Most users will use this class.
ezcMail
If ezcMailComposer does not have the functionality you require, you can use the ezcMail class to build MIME-structured mail from scratch. This requires basic knowledge about how a mail is structured.
ezcMailAddress
This small class represents a mail address with an optional name. It is used by both ezcMailComposer and ezcMail to set recipient addresses.
ezcMailParser
This class parses mail messages from text into ezcMail structures. You can use it together with the mail retrieval transport classes.
ezcMailSmtpTransport
Sends mails using an SMTP server. After sending a mail, the connection can be kept alive so that the next mail sent uses the same connection, speeding up the process.
ezcMailMtaTransport
Sends mails using the PHP mail() function.
ezcMailPop3Transport
Connects to a POP3 server and allows the fetching and deleting of mails.
ezcMailImapTransport
Connects to an IMAP server and allows operations on mails in a mailbox (fetch, delete) and operations on mailboxes (create, delete, rename, append).

Usage

Transport protocols

The Mail component provides transport protocols for both sending and retrieving mail.

For sending mail, the following protocols are supported:

For mail retrieval we currently support the following protocols:

Mail retrieval from other sources include:

Mail parsers

After using a mail retrieval transport to fetch a set of mails, a mail parser can be used to go through the set and extract the needed information like subject, sender, date and attachments from each mail in the set. The ezcMailParser class is used for this purpose.

Mail parts

The ezcMail component supports a wide variety of mail parts that can be used when sending or retrieving mails:

  • ezcMailFile - mail attachment from an existing file
  • ezcMailStreamFile - mail attachment from an open stream
  • ezcMailVirtualFile - mail attachment from a string in memory
  • ezcMailMultipartAlternative - used to bundle a group of mail parts where only one should be shown
  • ezcMailMultipartDigest - used to bundle a list of mail objects
  • ezcMailMultipartMixed - used to bundle an ordered list of mail parts
  • ezcMailMultipartRelated - intended for mail parts consisting of several inter-related body parts
  • ezcMailMultipartReport - used for sending delivery status notifications
  • ezcMailDeliveryStatus - used for sending delivery status notifications
  • ezcMailRfc822Digest - used to insert another mail into a mail
  • ezcMailText - used for plain text

Mail tools

In the ezcMailTools class, you will find various useful static methods that can be used in your applications:

See the ezcMailTools example below for information on how to use these methods.

Building and sending mail

eZ components provides two ways to create mail. The simplest is to use the composer class ezcMailComposer. Using the composer you can send plain text messages, HTML messages with images and messages with attachments. If you require more advanced messages you can also customize them entirely by building it from the scratch using the various part types in ezcMail. The part types are structured the same way as the underlying mail MIME types.

Sending 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. // Create a new mail composer object
  5. $mail = new ezcMailComposer();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Adrian Ripburger' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'receiver@example.com''Maureen Corley' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "This is the subject of the example mail";
 15. 
 16. // Specify the body text of the mail
 17. $mail->plainText "This is the body of the example mail.";
 18. 
 19. // Generate the mail
 20. $mail->build();
 21. 
 22. // Create a new MTA transport object
 23. $transport = new ezcMailMtaTransport();
 24. 
 25. // Use the MTA transport to send the created mail object
 26. $transport->send$mail );
 27. 
 28. ?>

Sending a mail with HTML, inline images and attachments

This example shows how to send a mail with HTML text, images and attachments using the ezcMailComposer class.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new mail composer object
  5. $mail = new ezcMailComposer();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'john@example.com''John Doe' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'cindy@example.com''Cindy Doe' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "Example of an HTML email with attachments";
 15. 
 16. // Specify the plain text of the mail
 17. $mail->plainText "Here is the text version of the mail. This is displayed if the client can not understand HTML";
 18. 
 19. // Specify the html text of the mail
 20. $mail->htmlText "<html>Here is the HTML version of your mail with an image: <img src='file://path_to_image.jpg' /></html>";
 21. 
 22. // Add an attachment to the mail
 23. $mail->addAttachment'path_to_attachment.file' );
 24. 
 25. // Build the mail object
 26. $mail->build();
 27. 
 28. // Create a new MTA transport object
 29. $transport = new ezcMailTransportMta();
 30. 
 31. // Use the MTA transport to send the created mail object
 32. $transport->send$mail ); 
 33. 
 34. ?>

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. // Create a new mail object
  5. $mail = new ezcMail();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Boston Low' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'receiver@example.com''Maggie Robbins' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "This is the subject of the example mail";
 15. 
 16. // Specify the body text of the mail as a ezcMailText object
 17. $mail->body = new ezcMailText"This is the body of the example mail." );
 18. 
 19. // Create a new MTA transport object
 20. $transport = new ezcMailMtaTransport();
 21. 
 22. // Use the MTA transport to send the created mail object
 23. $transport->send$mail );
 24. 
 25. ?>

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. // Create a new mail object
  5. $mail = new ezcMail();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Bernard Bernoulli' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'receiver@example.com''Wendy' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "This is the subject of the example mail";
 15. 
 16. // Create a text part to be added to the mail
 17. $textPart = new ezcMailText"This is the body of the example mail." );
 18. 
 19. // Create a file attachment to be added to the mail
 20. $fileAttachment = new ezcMailFile"~/myfile.jpg" );
 21. 
 22. // Specify the body of the mail as a multipart-mixed of the text part and the file attachment
 23. $mail->body = new ezcMailMultipartMixed$textPart$fileAttachment );
 24. 
 25. // Create a new MTA transport object
 26. $transport = new ezcMailMtaTransport();
 27. 
 28. // Use the MTA transport to send the created mail object
 29. $transport->send$mail );
 30. 
 31. ?>

Building MIME structures that work

When you build mail mail from scratch most combinations of MailParts will produce valid messages. Unfortunately, even though a message is valid structurally that does not mean that all mail clients will display it properly. This section gives a few hints on what to do and what not to do.

  1. Ommit Multipart/Mixed parts with only one part. Some mail clients like Mozilla Thunderbird do not display these correctly. Of course, they are not necessary either.
  2. Mail with alternative text/HTML parts and common attachments can be implemented in many ways. However, we have only found one structure that seems to work across all clients: MultipartMixed( MultipartAlternative( TextPart, TextPart ), FilePart, ... )

Sending a mail using SMTP

This example displays how to send a mail with SMTP, by using an SSLv3 connection.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new mail composer object
  5. $mail = new ezcMailComposer();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Adrian Ripburger' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'receiver@example.com''Maureen Corley' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "This is the subject of the example mail";
 15. 
 16. // Specify the body text of the mail
 17. $mail->plainText "This is the body of the example mail.";
 18. 
 19. // Generate the mail
 20. $mail->build();
 21. 
 22. // Create a new SMTP transport object with an SSLv3 connection.
 23. // The port will be 465 by default, use the 4th argument to change it.
 24. // Username and password (2nd and 3rd arguments) are left blank, which means
 25. // the mail host does not need authentication.
 26. // Omit the 5th parameter if you want to use a plain connection
 27. // (or set connectionType to ezcMailSmtpTransport::CONNECTION_PLAIN).
 28. $transport = new ezcMailSmtpTransport'mailhost.example.com'''''null, array( 'connectionType' => ezcMailSmtpTransport::CONNECTION_SSLV) );
 29. 
 30. // Use the SMTP transport to send the created mail object
 31. $transport->send$mail );
 32. 
 33. ?>

Character encoding

Most of the world does not speak and write US ASCII and thus requires more advanced character encoding to display 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. // Create a new mail object
  5. $mail = new ezcMail();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Norwegian characters: æøå''iso-8859-1' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'reciever@example.com''More norwegian characters: æøå''iso-8859-1' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject 'Oslo ligger sør i Norge og har vært landets hovedstad i over 600 år.';
 15. 
 16. // Specify the charset of the subject
 17. $mail->subjectCharset 'iso-8859-1';
 18. 
 19. // Specify the body as a text part, also specifying it's charset
 20. $mail->body = new ezcMailText'Oslo be grunnlagt rundt 1048 av Harald Hardråde.''iso-8859-1' );
 21. 
 22. // Create a new MTA transport object
 23. $transport = new ezcMailMtaTransport();
 24. 
 25. // Use the MTA transport to send the created mail object
 26. $transport->send$mail );
 27. 
 28. ?>

You can of course choose and combine any available character sets. Make sure that the input text is encoded as specified, or you may get unexpected results.

Extending the Mail component

It is possible to extend the Mail component if you require part types that are not supported by default. The following two examples shows how you can implement support for digest mail messages as attachments to your mail. This functionality is available through the ezcMailRfc822Digest class. For the sake of this example, we will recreate it in the MailRFC822Digest class.

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 mail headers.

To make it work, we create the class RFC822Digest to add these headers:

  1. <?php
  2. 
  3. class RFC822Digest extends ezcMailPart
  4. {
  5.     private $mail null;
  6.     public function __constructezcMail $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 do not need to override generateHeaders() since we can simply set the headers we want directly on the object. We do need to override generateBody(), since we want to include the full text of the mail digest.

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new mail object
  5. $mail = new ezcMail();
  6. 
  7. // Specify the "from" mail address
  8. $mail->from = new ezcMailAddress'sender@example.com''Largo LaGrande' );
  9. 
 10. // Add one "to" mail address (multiple can be added)
 11. $mail->addTo( new ezcMailAddress'receiver@example.com''Wally B. Feed' ) );
 12. 
 13. // Specify the subject of the mail
 14. $mail->subject "This is the subject of the mail with a mail digest.";
 15. 
 16. // Create a text part to be added to the mail
 17. $textPart = new ezcMailText"This is the body of the mail with a mail digest." );
 18. 
 19. // Specify the body of the mail as a multipart-mixed of the text part and a RFC822 digest object
 20. // where $digest is an ezcMail object
 21. // and RFC822Digest is the class from the previous example
 22. $mail->body = new ezcMailMultipartMixed$textPart, new RFC822Digest$digest ) );
 23. 
 24. // Create a new MTA transport object
 25. $transport = new ezcMailMtaTransport();
 26. 
 27. // Use the MTA transport to send the created mail object
 28. $transport->send$mail );
 29. 
 30. ?>

Using the ezcMailTools class

In this example, we use the various methods from the ezcMailTools class.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. $mailAddresses = array(
  5.                         new ezcMailAddress'john@example.com''Jøhn Doe''ISO-8859-1' ),
  6.                         new ezcMailAddress'jane@example.com''Jane Doe' )
  7.                       );
  8. $addresses '=?ISO-8859-1?B?SsO4aG4gRG9l?= <john@example.com>, Jane Doe <jane@example.com';
  9. 
 10. // Convert ezcMailAddress to string representation
 11. var_dumpezcMailTools::composeEmailAddress$mailAddresses[0] ) );
 12. var_dumpezcMailTools::composeEmailAddresses$mailAddresses ) );
 13. 
 14. // Convert string to ezcMailAddress
 15. var_dumpezcMailTools::parseEmailAddress$addresses ) );
 16. var_dumpezcMailTools::parseEmailAddresses$addresses ) );
 17. 
 18. // Create a new mail object
 19. $mail = new ezcMail();
 20. $mail->from $mailAddresses[1];
 21. $mail->addTo$mailAddresses[0] );
 22. $mail->subject "Top secret";
 23. // Use the lineBreak() method
 24. $mail->body = new ezcMailText"Confidential" ezcMailTools::lineBreak() . "DO NOT READ" );
 25. $mail->generate();
 26. 
 27. // Create a reply message to the previous mail object
 28. $reply ezcMailTools::replyToMail$mail, new ezcMailAddress'test@example.com''Reply Guy' ) );
 29. 
 30. ?>

Mail retrieval and parsing

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

The Mail component currently allows you to fetch and parse mail messages from POP3, IMAP, 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.

Retrieving mail using POP3

The following example shows how to fetch messages from a POP3 account using various methods and to parse the messages for use.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new POP3 transport object by specifying the server name
  5. $pop3 = new ezcMailPop3Transport"pop3.example.com" );
  6. 
  7. // Authenticate to the POP3 server
  8. $pop3->authenticate"user""password" );
  9. 
 10. // Get the number of messages on the server and their combined size
 11. // in the variables $num and $size
 12.     $pop3->status$num$size );
 13. 
 14. // Get the list of message numbers on the server and their sizes
 15. // the returned array is something like: array( 1 => 1500, 2 => 45200 )
 16. // where the key is a message number and the value is the message size
 17.     $messages $pop3->listMessages();
 18. 
 19. // Get the list of message unique ids on the server and their sizes
 20. // the returned array is something like: array( 1 => '00000f543d324', 2 => '000010543d324' )
 21. // where the key is an message number and the value is the message unique id
 22.     $messages $pop3->listUniqueIdentifiers();
 23. 
 24. // Usually you will call one of these 3 fetch functions:
 25. 
 26.     // Fetch all messages on the server
 27.     $set $pop3->fetchAll();
 28. 
 29.     // Fetch one message from the server (here: get the message no. 2)
 30.     $set $pop3->fetchByMessageNr);
 31. 
 32.     // Fetch a range of messages from the server (here: get 4 messages starting from message no. 2)
 33.     $set $pop3->fetchFromOffset2);
 34. 
 35. // Delete a message from the server
 36.     $pop3->delete);
 37. 
 38. // Use this to keep the connection alive
 39.     $pop3->noop();
 40. 
 41. // Create a new mail parser object
 42. $parser = new ezcMailParser();
 43. 
 44. // Parse the set of messages retrieved from the server earlier
 45. $mail $parser->parseMail$set );
 46. 
 47. ?>

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

Retrieving mail using IMAP

The following example shows how to fetch messages from an IMAP account using various functions and to parse the messages for use.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new IMAP transport object by specifying the server name
  5. $imap = new ezcMailImapTransport"imap.example.com" );
  6. 
  7. // Authenticate to the IMAP server
  8. $imap->authenticate"user""password" );
  9. 
 10. // Select the Inbox mailbox
 11. $imap->selectMailbox'Inbox' );
 12. 
 13. // Get the number of messages on the server, combined size, number of recent
 14. // messages and number of unseen messages
 15. // in the variables $num, $size, $recent, $unseen
 16.     $imap->status$num$size$recent$unseen );
 17. 
 18. // Get the list of message numbers on the server and their sizes
 19. // the returned array is something like: array( 1 => 1500, 2 => 45200 )
 20. // where the key is a message number and the value is the message size
 21.     $messages $imap->listMessages();
 22. 
 23. // Get the list of message unique ids on the server and their sizes
 24. // the returned array is something like: array( 1 => '15', 2 => '16' )
 25. // where the key is an message number and the value is the message unique id
 26.     $messages $imap->listUniqueIdentifiers();
 27. 
 28. // Usually you will call one of these 5 fetch functions:
 29. 
 30.     // Fetch all messages on the server
 31.     $set $imap->fetchAll();
 32. 
 33.     // Fetch one message from the server (here: get the message no. 2)
 34.     $set $imap->fetchByMessageNr);
 35. 
 36.     // Fetch a range of messages from the server (here: get 4 messages starting from message no. 2)
 37.     $set $imap->fetchFromOffset2);
 38. 
 39.     // Fetch messages which have a certain flag
 40.     // See the function description for a list of supported flags
 41.     $set $imap->fetchByFlag"DELETED" );
 42. 
 43.     // Fetch a range of messages sorted by a criteria
 44.     // Use this to page through a mailbox
 45.     // See the function description for a list of criterias and for how to sort ascending or descending
 46.     $set $imap->sortFromOffset110"Date" );
 47. 
 48. // Delete a message from the server (message is not physically deleted, but it's
 49. // list of flags get the "Deleted" flag.
 50.     $imap->delete);
 51. 
 52. // Use this to permanently delete the messages flagged with "Deleted"
 53.     $imap->expunge();
 54. 
 55. // Use this to keep the connection alive
 56.     $imap->noop();
 57. 
 58. // Create a new mail parser object
 59. $parser = new ezcMailParser();
 60. 
 61. // Parse the set of messages retrieved from the server earlier
 62. $mail $parser->parseMail$set );
 63. 
 64. ?>

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

Additional usage of the IMAP transport

The IMAP transport supports multiple mailboxes. In the following example, we work with mailboxes and flags.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new IMAP transport object by specifying the server name
  5. $imap = new ezcMailImapTransport"imap.example.com" );
  6. 
  7. // Authenticate to the IMAP server
  8. $imap->authenticate"user""password" );
  9. 
 10. // Select the Inbox mailbox
 11. $imap->selectMailbox'Inbox' );
 12. 
 13. // List the capabilities of the IMAP server
 14.     $capabilities $imap->capability();
 15. 
 16. // List existing mailboxes
 17.     $mailboxes $imap->listMailboxes"""*" );
 18. 
 19. // Create a new mailbox
 20.     $imap->createMailbox"Reports 2006" );
 21. 
 22. // Delete a mailbox
 23.     $imap->deleteMailbox"Reports 2005" );
 24. 
 25. // Rename a mailbox
 26.     $imap->renameMailbox"Reports 2006""Reports" );
 27. 
 28. // Copy messages from the selected mailbox (here: Inbox) to another mailbox
 29.     $imap->copyMessages"1,2,4""Reports" );
 30. 
 31. // Set a flag to messages
 32. // See the function description for a list of supported flags
 33.     $imap->setFlag"1,2,4""DELETED" );
 34. 
 35. // Clears a flag from messages
 36. // See the function description for a list of supported flags
 37.     $imap->setFlag"1,2,4""SEEN" );
 38. 
 39. // Append a message to a mailbox. $mail must contain the mail as text
 40. // Use this with a "Sent" or "Drafts" mailbox
 41.     $imap->append"Sent"$mail );
 42. 
 43. // Create a new mail parser object
 44. $parser = new ezcMailParser();
 45. 
 46. // Parse the set of messages retrieved from the server earlier
 47. $mail $parser->parseMail$set );
 48. 
 49. ?>

Working with transport options

The POP3, IMAP and SMTP transports allow options to be specified when calling the transport constructors. These options are implemented in the classes ezcMailPop3TransportOptions, ezcMailImapTransportOptions and ezcMailSmtpTransportOptions. In the following example, we specify options when calling the POP3 transport constructor.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new POP3 transport with a plain connection (default port is 110,
  5. // you can specify a different one using the second parameter of the constructor).
  6. // A timeout option is specified to be 10 seconds (default is 5).
  7. // Another option to be specified is the authenticationMethod as APOP (default is plain text)
  8. $pop3 = new ezcMailPop3Transport"imap.example.com"null,
  9.             array( 'timeout' => 10,
 10.                    'authenticationMethod' => ezcMailPop3Transport::AUTH_APOP
 11.                  ) );
 12. 
 13. // Authenticate to the POP3 server
 14. $pop3->authenticate"user""password" );
 15. 
 16. ?>

Using SSL with POP3 and IMAP

The POP3 and IMAP transports allow SSL connections (if the mail server supports them). In the following example, we connect to an IMAP server using an SSL connection.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new IMAP transport with an SSL connection (default port is 993,
  5. // you can specify a different one using the second parameter of the constructor).
  6. $imap = new ezcMailImapTransport"imap.example.com"null,
  7.             array( 'ssl' => true ) );
  8. 
  9. // Authenticate to the IMAP server
 10. $imap->authenticate"user""password" );
 11. 
 12. // Select the Inbox mailbox
 13. $imap->selectMailbox'Inbox' );
 14. 
 15. ?>

Retrieving mail from mbox files

The following example shows how to fetch all messages from an mbox file and to parse the messages for use.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new Mbox transport object by specifiying an existing mbox file name
  5. $mbox = new ezcMailMboxTransport"/path/file.mbox" );
  6. 
  7. // Fetch all messages from the mbox file
  8. $set $mbox->fetchAll();
  9. 
 10. // Create a new mail parser object
 11. $parser = new ezcMailParser();
 12. 
 13. // Parse the set of messages retrieved from the mbox file earlier
 14. $mail $parser->parseMail$set );
 15. 
 16. ?>

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

Parsing a message set

The following example shows how to parse a message set retrieved from an IMAP or POP3 account, an mbox file, a single mail file or a variable.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // Create a new mail parser object
  5. $parser = new ezcMailParser();
  6. 
  7. // $set is a message set got from an IMAP, POP3 account or Mbox file
  8. // like for example:
  9. // $mbox = new ezcMailMboxTransport( "/path/file.mbox" );
 10. // $set = $mbox->fetchAll();
 11. $mail $parser->parseMail$set );
 12. 
 13. for ( $i 0$i count$mail ); $i++ )
 14. {
 15.     // Process $mail[$i] such as use $mail[$i]->subject, $mail[$i]->body
 16.     echo "From: {$mail[$i]->from}, Subject: {$mail[$i]->subject}\n";
 17. }
 18. 
 19. ?>

For a more detailed example on how to use a mail object, please see the display example.

For an example on how to display a listing of mails, please see the mail listing example.

For a list of supported mail-related RFCs, please see the RFCs list.

Troubleshooting

MTA: Qmail

Qmail insists on only using "\n" line breaks and will send garbled messages with the default "\r\n" setting. To fix this issue, use ezcMailTools::setLineBreak( "\n" ) before sending mail.

MTA: Sendmail relaying denied

This can happen when the SMTP server you try to use has disabled the sending of mail from computers not connected to its network, or if it requires authentication. Talk to the administrator of the SMTP server to see what the requirements are to send mail.

Check also that sendmail is installed and configured correctly.

For Windows, you need to specify a valid SMTP server in php.ini, or you can download a "fake" sendmail from the internet.

IMAP: Authentication failed

Sometimes the IMAP transport fails to authenticate, in which case the authenticate() method will return false. The application should detect when this occurs and attempt authentication again (for example, for a preset number of times such as three).

Last updated: Wed, 28 Nov 2007