The mail component provides transport protocols for both sending and retrieving
mail.
For sending mail we support the following protocols:
For mail retrieval we currently support the following protocols:
Mail retrieval from other sources:
After using a mail retrieval trasport 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, attachments from each mail in the set. The ezcMailParser
class is used for this purpose.
The ezcMail component supports a wide variety of mail parts which 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
- ezcMailMultipart - support for all multipart parts
- 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
- ezcMailRfc822Digest - used to insert mail into mail
- ezcMailText - used for plain text
In the ezcMailTools class you will find various useful static methods which can be
used in your applications:
See the Mail tools example below for how to use these methods.
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. ?>
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. ?>
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. ?>
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. // 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 set. Make sure
that the input text is in the encoding specified or you may get unexpected
results.
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. 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. ?>
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. // 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. ?>
Many applications have a 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 components 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.
The following example shows how to fetch messages from a POP3 account using
various methods and parse them for usage.
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( 2 );
31.
32. // Fetch a range of messages from the server (here: get 4 messages starting from message no. 2)
33. $set = $pop3->fetchFromOffset( 2, 4 );
34.
35. // Delete a message from the server
36. $pop3->delete( 1 );
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 as the
MIME structure of the mail.
The following example shows how to fetch messages from an IMAP account using
various functions and parse them for usage.
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( 2 );
35.
36. // Fetch a range of messages from the server (here: get 4 messages starting from message no. 2)
37. $set = $imap->fetchFromOffset( 2, 4 );
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->sortFromOffset( 1, 10, "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( 1 );
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. $pop3->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 as the
MIME structure of the mail.
The IMAP transport supports multiple mailboxes. In the following example it is
shown how to 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. ?>
The following example shows how to fetch all messages from an MBOX file and
parse them for usage.
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 as the
MIME structure of the mail.
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 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 of how to use a mail object please see the
display example.
Qmail insists it should only have "\n" linebreaks and will send garbled messages
with the default "\r\n" setting. Use ezcMailTools::setLineBreak( "\n" ) before
sending mail to fix this issue.
This can happen in case the administrator of the SMTP server you try to use
disables the sending of mail from computers not connected to their network, or
if requires authentication. Talk to the administrator of the SMTP server and
see what are the requirements to send email.
Check also that your 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 Internet.
Sometimes the IMAP transport fails to authenticate, in which case the
authenticate() method will return false. The application should detect when
this is happening and attempt authentication again (for example for a preset
number of times such as 3).
