## Apache Zeta Components Manual :: Docs For Class ezcMail

### Mail::ezcMail

### Class ezcMail

The main mail class.

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-> addTo (new 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);

By default, the ezcMail class will generate a mail with the Bcc header inside, and leave it to the SMTP server to strip the Bcc header. This can pose a problem with some SMTP servers which do not strip the Bcc header (issue #16154: Bcc headers are not stripped when using SMTP). Use the option stripBccHeader from ezcMailOptions to delete the Bcc header from the mail before it is sent.

Example:

Source for this file: /Mail/src/mail.php

    ezcMailPart
       |
       --ezcMail

Version: | //autogen//

### Descendants

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.
ezcMailOptions | read/write | `$options` Options for generating mail. See ezcMailOptions.
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.

### Member Variables

protected ezcMailOptions | `$options` Holds the options for this class.

### Inherited Member Variables

From ezcMailPart
protected | `ezcMailPart::$properties`

### Method Summary

protected static void | `collectPart( $context , $mail )` Saves $mail in the $context object.
public ezcMail | `__construct( [ $options = null] )` 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.
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 mixed | `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

#### collectPart

static 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 |

#### __construct

ezcMail __construct( [ezcMailOptions $options = null] )

Constructs an empty ezcMail object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcMailOptions |

##### 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 |

#### 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")
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,
12. // 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. classApp
2. {
3. publicstaticfunctionsaveMailPart($context,$mailPart)
4. {
5. // code to save the $mailPart object to disk
6. }
7. }
9. // use the saveMailPart() function as a callback in walkParts()
10. // where $mail is an ezcMail object.
11. $context=new ezcMailPartWalkContext (array('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 |

Documentation generated by phpDocumentor 1.4.3