Path

ez components / documentation / api reference / 2009.1rc1 / mail


eZ Components 2009.1rc1

Mail: ezcMail

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

Class: ezcMail

The main mail class. [source]
You can use ezcMail together with the other classes derived from ezcMailPart to build email messages. When the mail is built, use the Transport classes to send the mail.
This example builds and sends a simple text mail message:
1.  $mail new ezcMail;
2.  $mail->from new ezcMailAddress'sender@example.com''Adrian Ripburger' );
3.  $mail->addTonew ezcMailAddress'receiver@example.com''Maureen Corley' ) );
4.  $mail->subject "Hi";
5.  $mail->body new ezcMailText"I just mail to say I love you!" );
6.  $transport new ezcMailMtaTransport();
7.  $transport->send$mail );
You can also derive your own mail classes from this class if you have special requirements. An example of this is the ezcMailComposer class which is a convenience class to send simple mail structures and HTML mail.
There are several headers you can set on the mail object to achieve various effects:
  • Reply-To - Set this to an email address if you want people to reply to an address other than the from address.
  • Errors-To - If the mail can not be delivered the error message will be sent to this address.

Parents

ezcMailPart
   |
   --ezcMail

Descendents

Child Class Description
ezcMailComposer Convenience class for writing mail.

Constants

BASE64 = "base64" Base 64 encoding.
BINARY = "binary" Binary encoding.
EIGHT_BIT = "8bit" 8 bit encoding.
QUOTED_PRINTABLE = "quoted-printable" Quoted printable encoding.
SEVEN_BIT = "7bit" 7 bit encoding.

Properties

array(ezcMailAddress) read/write  $bcc
Contains an array of ezcMailAddress objects.
ezcMailPart read/write  $body
The body part of the message.
array(ezcMailAddress) read/write  $cc
Contains an array of ezcMailAddress objects.
ezcMailAddress read/write  $from
Contains the from address as an ezcMailAddress object.
string read  $messageId
The message ID of the message. Treat as read-only unless you're 100% sure what you're doing. Also accessible through the deprecated property messageID.
ezcMailAddress read/write  $returnPath
Contains the Return-Path address as an ezcMailAddress object.
string read/write  $subject
Contains the subject of the e-mail. Use setSubject if you require a special encoding.
string read/write  $subjectCharset
The encoding of the subject.
integer read  $timestamp
The date/time of when the message was sent as Unix Timestamp.
array(ezcMailAddress) read/write  $to
Contains an array of ezcMailAddress objects.

Inherited Member Variables

From ezcMailPart:
protected  ezcMailPart::$properties

Method Summary

public ezcMail __construct( )
Constructs an empty ezcMail object.
public void addBcc( $address )
Adds the ezcMailAddress $address to the list of 'bcc' recipients.
public void addCc( $address )
Adds the ezcMailAddress $address to the list of 'cc' recipients.
public void addTo( $address )
Adds the ezcMailAddress $address to the list of 'to' recipients.
protected static void collectPart( $context, $mail )
Saves $mail in the $context object.
public array(ezcMailPart) fetchParts( [$filter = null], [$includeDigests = false] )
Returns an array of mail parts from the current mail.
public string generateBody( )
Returns the generated body part of this mail.
public string generateHeaders( )
Returns the generated headers for the mail.
public void walkParts( $context, $mail )
Walks recursively through the mail parts in the specified mail object.

Inherited Methods

From ezcMailPart :
public ezcMailPart ezcMailPart::__construct()
Constructs a new mail part.
public void ezcMailPart::appendExcludeHeaders()
The array $headers will be excluded when the headers are generated.
public string ezcMailPart::generate()
Returns the complete mail part including both the header and the body as a string.
public abstract string ezcMailPart::generateBody()
Returns the body of this part as a string.
public string ezcMailPart::generateHeaders()
Returns the headers set for this part as a RFC 822 string.
public string ezcMailPart::getHeader()
Returns the RAW value of the header $name.
protected string ezcMailPart::getHeaderCharset()
Returns the charset registered for the header $name.
public void ezcMailPart::setHeader()
Sets the header $name to the value $value and its charset to $charset.
protected void ezcMailPart::setHeaderCharset()
Sets the charset of the header $name to $value.
public void ezcMailPart::setHeaders()
Adds the headers $headers.

Methods

__construct

ezcMail __construct( )
Constructs an empty ezcMail object.

Redefinition of

Method Description
ezcMailPart::__construct() Constructs a new mail part.

Redefined in descendants as

Method Description
ezcMailComposer::__construct() Constructs an empty ezcMailComposer object.

addBcc

void addBcc( ezcMailAddress $address )
Adds the ezcMailAddress $address to the list of 'bcc' recipients.

Parameters

Name Type Description
$address ezcMailAddress  

addCc

void addCc( ezcMailAddress $address )
Adds the ezcMailAddress $address to the list of 'cc' recipients.

Parameters

Name Type Description
$address ezcMailAddress  

addTo

void addTo( ezcMailAddress $address )
Adds the ezcMailAddress $address to the list of 'to' recipients.

Parameters

Name Type Description
$address ezcMailAddress  

collectPart

void collectPart( ezcMailPartWalkContext $context, ezcMailPart $mail )
Saves $mail in the $context object.
This function is used as a callback in the fetchParts() method.

Parameters

Name Type Description
$context ezcMailPartWalkContext  
$mail ezcMailPart  

fetchParts

array(ezcMailPart) fetchParts( [array(string) $filter = null], [bool $includeDigests = false] )
Returns an array of mail parts from the current mail.
The array returned contains objects of classes:
  • ezcMailText
  • ezcMailFile
  • ezcMailRfc822Digest
If the method is called with $includeDigests as true, then the returned array will not contain ezcMailRfc822Digest objects, but instead the mail parts inside the digests. The parameter $filter can be used to restrict the returned mail parts, eg. $filter = array( 'ezcMailFile' ) to return only file mail parts.
A typical use for this function is to get a list of attachments from a mail. Example:
 1.  // $mail is an ezcMail object
 2.   $parts $mail->fetchParts();
 3.  // after the above line is executed, $parts will contain an array of mail parts objects,
 4.  // for example one ezcMailText object ($parts[0]) and two ezcMailRfc822Digest objects ($parts[1] and $parts[2]).
 5.  // the ezcMailText object will be used to render the mail text, and the
 6.  // other two objects will be displayed as links ("view attachment")
 7.  
 8.  // when user clicks on one of the two attachments, the parts of that attachment
 9.  // must be retrieved in order to render the attached digest:
10.   $subparts $parts[1]->mail->fetchParts();
11.  // after the above line is executed, $subparts will contain an array of mail parts objects,
11.  // for example one ezcMailText object and one ezcMailFile object

Parameters

Name Type Description
$filter array(string)  
$includeDigests bool  

generateBody

string generateBody( )
Returns the generated body part of this mail.
Returns an empty string if no body has been set.

Redefinition of

Method Description
ezcMailPart::generateBody() Returns the body of this part as a string.

generateHeaders

string generateHeaders( )
Returns the generated headers for the mail.
This method is called automatically when the mail message is built. You can re-implement this method in subclasses if you wish to set different mail headers than ezcMail.

Redefinition of

Method Description
ezcMailPart::generateHeaders() Returns the headers set for this part as a RFC 822 string.

walkParts

void walkParts( ezcMailPartWalkContext $context, ezcMailPart $mail )
Walks recursively through the mail parts in the specified mail object.
$context is an object of class ezcMailPartWalkContext, which must contain a valid callback function name to be applied to all mail parts. You can use the collectPart() method, or create your own callback function which can for example save the mail parts to disk or to a database.
For the properties you can set to the walk context see: ezcMailPartWalkContext
Example:
 1.  class App
 2.  {
 3.      public static function saveMailPart$context$mailPart )
 4.      {
 5.          // code to save the $mailPart object to disk
 6.      }
 7.  }
 8.  
 9.  // use the saveMailPart() function as a callback in walkParts()
10.  // where $mail is an ezcMail object.
11.   $context new ezcMailPartWalkContextarray'App''saveMailPart' ) );
12.  $context->includeDigests true// if you want to go through the digests in the mail
13.   $mail->walkParts$context$mail );

Parameters

Name Type Description
$context ezcMailPartWalkContext  
$mail ezcMailPart  

Last updated: Mon, 22 Jun 2009