documentation/manual/en/module_specs/Zend_Mail-Introduction.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.mail.introduction">
   4     <title>Introduction</title>
   5
   6     <sect2 id="zend.mail.introduction.getting-started">
   7         <title>Getting started</title>
   8
   9         <para>
  10             <classname>Zend_Mail</classname> provides generalized functionality to compose and send
  11             both text and <acronym>MIME</acronym>-compliant multipart e-mail messages. Mail can be
  12             sent with <classname>Zend_Mail</classname> via the default
  13             <classname>Zend_Mail_Transport_Sendmail</classname> transport or via
  14             <classname>Zend_Mail_Transport_Smtp</classname>.
  15         </para>
  16
  17         <example id="zend.mail.introduction.example-1">
  18             <title>Simple E-Mail with Zend_Mail</title>
  19
  20             <para>
  21                 A simple e-mail consists of some recipients, a subject, a body and a sender. To send
  22                 such a mail using <classname>Zend_Mail_Transport_Sendmail</classname>, do the
  23                 following:
  24             </para>
  25
  26             <programlisting language="php"><![CDATA[
  27 $mail = new Zend_Mail();
  28 $mail->setBodyText('This is the text of the mail.');
  29 $mail->setFrom('somebody@example.com', 'Some Sender');
  30 $mail->addTo('somebody_else@example.com', 'Some Recipient');
  31 $mail->setSubject('TestSubject');
  32 $mail->send();
  33 ]]></programlisting>
  34         </example>
  35
  36         <note>
  37             <title>Minimum definitions</title>
  38
  39             <para>
  40                 In order to send an e-mail with <classname>Zend_Mail</classname> you have to specify
  41                 at least one recipient, a sender (e.g., with <methodname>setFrom()</methodname>),
  42                 and a message body (text and/or <acronym>HTML</acronym>).
  43             </para>
  44         </note>
  45
  46         <para>
  47             For most mail attributes there are "get" methods to read the information stored in the
  48             mail object. for further details, please refer to the <acronym>API</acronym>
  49             documentation. A special one is <methodname>getRecipients()</methodname>. It returns an
  50             array with all recipient e-mail addresses that were added prior to the method call.
  51         </para>
  52
  53         <para>
  54             For security reasons, <classname>Zend_Mail</classname> filters all header fields to
  55             prevent header injection with newline (<code>\n</code>) characters.
  56             Double quotation is changed to single quotation and angle brackets to square brackets in
  57             the name of sender and recipients. If the marks are in email address, the marks will be
  58             removed.
  59         </para>
  60
  61         <para>
  62             You also can use most methods of the <classname>Zend_Mail</classname> object with a
  63             convenient fluent interface.
  64         </para>
  65
  66         <programlisting language="php"><![CDATA[
  67 $mail = new Zend_Mail();
  68 $mail->setBodyText('This is the text of the mail.')
  69     ->setFrom('somebody@example.com', 'Some Sender')
  70     ->addTo('somebody_else@example.com', 'Some Recipient')
  71     ->setSubject('TestSubject')
  72     ->send();
  73 ]]></programlisting>
  74     </sect2>
  75
  76     <sect2 id="zend.mail.introduction.sendmail">
  77         <title>Configuring the default sendmail transport</title>
  78
  79         <para>
  80             The default transport for a <classname>Zend_Mail</classname> instance is
  81             <classname>Zend_Mail_Transport_Sendmail</classname>. It is essentially a wrapper to the
  82             <acronym>PHP</acronym> <ulink
  83                 url="http://php.net/mail"><methodname>mail()</methodname></ulink> function. If you
  84             wish to pass additional parameters to the <ulink
  85                 url="http://php.net/mail"><methodname>mail()</methodname></ulink> function, simply
  86             create a new transport instance and pass your parameters to the constructor. The new
  87             transport instance can then act as the default <classname>Zend_Mail</classname>
  88             transport, or it can be passed to the <methodname>send()</methodname> method of
  89             <classname>Zend_Mail</classname>.
  90         </para>
  91
  92         <example id="zend.mail.introduction.sendmail.example-1">
  93             <title>
  94                 Passing additional parameters to the Zend_Mail_Transport_Sendmail transport
  95             </title>
  96
  97             <para>
  98                 This example shows how to change the Return-Path of the <ulink
  99                     url="http://php.net/mail"><methodname>mail()</methodname></ulink> function.
 100             </para>
 101
 102             <programlisting language="php"><![CDATA[
 103 $tr = new Zend_Mail_Transport_Sendmail('-freturn_to_me@example.com');
 104 Zend_Mail::setDefaultTransport($tr);
 105
 106 $mail = new Zend_Mail();
 107 $mail->setBodyText('This is the text of the mail.');
 108 $mail->setFrom('somebody@example.com', 'Some Sender');
 109 $mail->addTo('somebody_else@example.com', 'Some Recipient');
 110 $mail->setSubject('TestSubject');
 111 $mail->send();
 112 ]]></programlisting>
 113         </example>
 114
 115         <note>
 116             <title>Safe mode restrictions</title>
 117
 118             <para>
 119                 The optional additional parameters will be cause the <ulink
 120                     url="http://php.net/mail"><methodname>mail()</methodname></ulink> function to
 121                 fail if <acronym>PHP</acronym> is running in safe mode.
 122             </para>
 123         </note>
 124
 125         <warning>
 126             <title>Sendmail Transport and Windows</title>
 127
 128             <para>
 129                 As the <acronym>PHP</acronym> manual states the <methodname>mail()</methodname>
 130                 function has different behaviour on Windows and on *nix based systems. Using the
 131                 Sendmail Transport on Windows will not work in combination with
 132                 <methodname>addBcc()</methodname>. The <methodname>mail()</methodname> function will
 133                 sent to the BCC recipient such that all the other recipients can see him as
 134                 recipient!
 135             </para>
 136
 137             <para>
 138                 Therefore if you want to use BCC on a windows server, use the SMTP
 139                 transport for sending!
 140             </para>
 141         </warning>
 142     </sect2>
 143 </sect1>
 144 <!--
 145 vim:se ts=4 sw=4 et:
 146 -->