1 Creating Messages

     2 =================

     3 

     4 Creating messages in Swift Mailer is done by making use of the various MIME

     5 entities provided with the library.  Complex messages can be quickly created

     6 with very little effort.

     7 

     8 Quick Reference for Creating a Message

     9 ---------------------------------------

    10 

    11 You can think of creating a Message as being similar to the steps you perform

    12 when you click the Compose button in your mail client.  You give it a subject,

    13 specify some recipients, add any attachments and write your message.

    14 

    15 To create a Message:

    16 

    17 * Call the ``newInstance()`` method of ``Swift_Message``.

    18 

    19 * Set your sender address (``From:``) with ``setFrom()`` or ``setSender()``.

    20 

    21 * Set a subject line with ``setSubject()``.

    22 

    23 * Set recipients with ``setTo()``, ``setCc()`` and/or ``setBcc()``.

    24 

    25 * Set a body with ``setBody()``.

    26 

    27 * Add attachments with ``attach()``.

    28 

    29 .. code-block:: php

    30 

    31     require_once 'lib/swift_required.php';

    32 

    33     //Create the message

    34     $message = Swift_Message::newInstance()

    35 

    36       //Give the message a subject

    37       ->setSubject('Your subject')

    38 

    39       //Set the From address with an associative array

    40       ->setFrom(array('john@doe.com' => 'John Doe'))

    41 

    42       //Set the To addresses with an associative array

    43       ->setTo(array('receiver@domain.org', 'other@domain.org' => 'A name'))

    44 

    45       //Give it a body

    46       ->setBody('Here is the message itself')

    47 

    48       //And optionally an alternative body

    49       ->addPart('<q>Here is the message itself</q>', 'text/html')

    50 

    51       //Optionally add any attachments

    52       ->attach(Swift_Attachment::fromPath('my-document.pdf'))

    53       ;

    54 

    55 Message Basics

    56 --------------

    57 

    58 A message is a container for anything you want to send to somebody else. There

    59 are several basic aspects of a message that you should know.

    60 

    61 An e-mail message is made up of several relatively simple entities that are

    62 combined in different ways to achieve different results. All of these entities

    63 have the same fundamental outline but serve a different purpose. The Message

    64 itself can be defined as a MIME entity, an Attachment is a MIME entity, all

    65 MIME parts are MIME entities -- and so on!

    66 

    67 The basic units of each MIME entity -- be it the Message itself, or an

    68 Attachment -- are its Headers and its body:

    69 

    70 .. code-block:: text

    71 

    72     Header-Name: A header value

    73     Other-Header: Another value

    74 

    75     The body content itself

    76 

    77 The Headers of a MIME entity, and its body must conform to some strict

    78 standards defined by various RFC documents. Swift Mailer ensures that these

    79 specifications are followed by using various types of object, including

    80 Encoders and different Header types to generate the entity.

    81 

    82 The Structure of a Message

    83 ~~~~~~~~~~~~~~~~~~~~~~~~~~

    84 

    85 Of all of the MIME entities, a message -- ``Swift_Message``

    86 is the largest and most complex. It has many properties that can be updated

    87 and it can contain other MIME entities -- attachments for example --

    88 nested inside it.

    89 

    90 A Message has a lot of different Headers which are there to present

    91 information about the message to the recipients' mail client. Most of these

    92 headers will be familiar to the majority of users, but we'll list the basic

    93 ones. Although it's possible to work directly with the Headers of a Message

    94 (or other MIME entity), the standard Headers have accessor methods provided to

    95 abstract away the complex details for you. For example, although the Date on a

    96 message is written with a strict format, you only need to pass a UNIX

    97 timestamp to ``setDate()``.

    98 

    99 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   100 | Header                        | Description                                                                                                                        | Accessors                                   |

   101 +===============================+====================================================================================================================================+=============================================+

   102 | ``Message-ID``                | Identifies this message with a unique ID, usually containing the domain name and time generated                                    | ``getId()`` / ``setId()``                   |

   103 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   104 | ``Return-Path``               | Specifies where bounces should go (Swift Mailer reads this for other uses)                                                         | ``getReturnPath()`` / ``setReturnPath()``   |

   105 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   106 | ``From``                      | Specifies the address of the person who the message is from. This can be multiple addresses if multiple people wrote the message.  | ``getFrom()`` / ``setFrom()``               |

   107 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   108 | ``Sender``                    | Specifies the address of the person who physically sent the message (higher precedence than ``From:``)                             | ``getSender()`` / ``setSender()``           |

   109 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   110 | ``To``                        | Specifies the addresses of the intended recipients                                                                                 | ``getTo()`` / ``setTo()``                   |

   111 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   112 | ``Cc``                        | Specifies the addresses of recipients who will be copied in on the message                                                         | ``getCc()`` / ``setCc()``                   |

   113 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   114 | ``Bcc``                       | Specifies the addresses of recipients who the message will be blind-copied to. Other recipients will not be aware of these copies. | ``getBcc()`` / ``setBcc()``                 |

   115 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   116 | ``Reply-To``                  | Specifies the address where replies are sent to                                                                                    | ``getReplyTo()`` / ``setReplyTo()``         |

   117 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   118 | ``Subject``                   | Specifies the subject line that is displayed in the recipients' mail client                                                        | ``getSubject()`` / ``setSubject()``         |

   119 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   120 | ``Date``                      | Specifies the date at which the message was sent                                                                                   | ``getDate()`` / ``setDate()``               |

   121 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   122 | ``Content-Type``              | Specifies the format of the message (usually text/plain or text/html)                                                              | ``getContentType()`` / ``setContentType()`` |

   123 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   124 | ``Content-Transfer-Encoding`` | Specifies the encoding scheme in the message                                                                                       | ``getEncoder()`` / ``setEncoder()``         |

   125 +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

   126 

   127 Working with a Message Object

   128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   129 

   130 Although there are a lot of available methods on a message object, you only

   131 need to make use of a small subset of them. Usually you'll use

   132 ``setSubject()``, ``setTo()`` and

   133 ``setFrom()`` before setting the body of your message with

   134 ``setBody()``.

   135 

   136 Calling methods is simple. You just call them like functions, but using the

   137 object operator "``<![CDATA[->]]>``" to do so. If you've created

   138 a message object and called it ``$message`` then you'd set a

   139 subject on it like so:

   140 

   141 .. code-block:: php

   142 

   143     require_once 'lib/swift_required.php';  

   144 

   145     $message = Swift_Message::newInstance();

   146     $message->setSubject('My subject');

   147 

   148 All MIME entities (including a message) have a ``toString()``

   149 method that you can call if you want to take a look at what is going to be

   150 sent. For example, if you ``<![CDATA[echo

   151 $message->toString();]]>`` you would see something like this:

   152 

   153 .. code-block:: bash

   154 

   155     Message-ID: <1230173678.4952f5eeb1432@swift.generated>

   156     Date: Thu, 25 Dec 2008 13:54:38 +1100

   157     Subject: Example subject

   158     From: Chris Corbyn <chris@w3style.co.uk>

   159     To: Receiver Name <recipient@example.org>

   160     MIME-Version: 1.0

   161     Content-Type: text/plain; charset=utf-8

   162     Content-Transfer-Encoding: quoted-printable

   163 

   164     Here is the message

   165 

   166 We'll take a closer look at the methods you use to create your message in the

   167 following sections.

   168 

   169 Adding Content to Your Message

   170 ------------------------------

   171 

   172 Rich content can be added to messages in Swift Mailer with relative ease by

   173 calling methods such as setSubject(), setBody(), addPart() and attach().

   174 

   175 Setting the Subject Line

   176 ~~~~~~~~~~~~~~~~~~~~~~~~

   177 

   178 The subject line, displayed in the recipients' mail client can be set with the

   179 setSubject() method, or as a parameter to Swift_Message::newInstance().

   180 

   181 To set the subject of your Message:

   182 

   183 * Call the ``setSubject()`` method of the Message, or specify it at the time

   184   you create the message.

   185 

   186   .. code-block:: php

   187 

   188     // Pass it as a parameter when you create the message

   189     $message = Swift_Message::newInstance('My amazing subject');

   190 

   191     // Or set it after like this

   192     $message->setSubject('My amazing subject');

   193 

   194 Setting the Body Content

   195 ~~~~~~~~~~~~~~~~~~~~~~~~

   196 

   197 The body of the message -- seen when the user opens the message --

   198 is specified by calling the setBody() method. If an alternative body is to be

   199 included addPart() can be used.

   200 

   201 The body of a message is the main part that is read by the user. Often people

   202 want to send a message in HTML format (``text/html``), other

   203 times people want to send in plain text (``text/plain``), or

   204 sometimes people want to send both versions and allow the recipient to chose

   205 how they view the message.

   206 

   207 As a rule of thumb, if you're going to send a HTML email, always include a

   208 plain-text equivalent of the same content so that users who prefer to read

   209 plain text can do so.

   210 

   211 To set the body of your Message:

   212 

   213 * Call the ``setBody()`` method of the Message, or specify it at the time you

   214   create the message.

   215 

   216 * Add any alternative bodies with ``addPart()``.

   217 

   218 If the recipient's mail client offers preferences for displaying text vs. HTML then

   219 the mail client will present that part to the user where available.  In other cases

   220 the mail client will display the "best" part it can - usually HTML if you've included

   221 HTML.

   222 

   223 .. code-block:: php

   224 

   225     //Pass it as a parameter when you create the message

   226     $message = Swift_Message::newInstance('Subject here', 'My amazing body');  

   227 

   228     //Or set it after like this

   229     $message->setBody('My <em>amazing</em> body', 'text/html');

   230 

   231     //Add alternative parts with addPart()

   232     $message->addPart('My amazing body in plain text', 'text/plain');

   233 

   234 Attaching Files

   235 ---------------

   236 

   237 Attachments are downloadable parts of a message and can be added by calling

   238 the attach() method on the message. You can add attachments that exist on

   239 disk, or you can create attachments on-the-fly.

   240 

   241 Attachments are actually an interesting area of Swift Mailer and something

   242 that could put a lot of power at your fingertips if you grasp the concept

   243 behind the way a message is held together.

   244 

   245 Although we refer to files sent over e-mails as "attachments" -- because

   246 they're attached to the message -- lots of other parts of the message are

   247 actually "attached" even if we don't refer to these parts as attachments.

   248 

   249 File attachments are created by the ``Swift_Attachment`` class

   250 and then attached to the message via the ``attach()`` method on

   251 it. For all of the "every day" MIME types such as all image formats, word

   252 documents, PDFs and spreadsheets you don't need to explicitly set the

   253 content-type of the attachment, though it would do no harm to do so. For less

   254 common formats you should set the content-type -- which we'll cover in a

   255 moment.

   256 

   257 Attaching Existing Files

   258 ~~~~~~~~~~~~~~~~~~~~~~~~

   259 

   260 Files that already exist, either on disk or at a URL can be attached to a

   261 message with just one line of code, using Swift_Attachment::fromPath().

   262 

   263 You can attach files that exist locally, or if your PHP installation has

   264 ``allow_url_fopen`` turned on you can attach files from other

   265 websites.

   266 

   267 To attach an existing file:

   268 

   269 * Create an attachment with ``Swift_Attachment::fromPath()``.

   270 

   271 * Add the attachment to the message with ``attach()``.

   272 

   273 The attachment will be presented to the recipient as a downloadable file with

   274 the same filename as the one you attached.

   275 

   276 .. code-block:: php

   277 

   278     //Create the attachment

   279     // * Note that you can technically leave the content-type parameter out

   280     $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');  

   281 

   282     //Attach it to the message

   283     $message->attach($attachment);

   284 

   285 

   286     //The two statements above could be written in one line instead

   287     $message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));

   288 

   289 

   290     //You can attach files from a URL if allow_url_fopen is on in php.ini

   291     $message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

   292 

   293 Setting the Filename

   294 ~~~~~~~~~~~~~~~~~~~~

   295 

   296 Usually you don't need to explicitly set the filename of an attachment because

   297 the name of the attached file will be used by default, but if you want to set

   298 the filename you use the setFilename() method of the Attachment.

   299 

   300 To change the filename of an attachment:

   301 

   302 * Call its ``setFilename()`` method.

   303 

   304 The attachment will be attached in the normal way, but meta-data sent inside

   305 the email will rename the file to something else.

   306 

   307 .. code-block:: php

   308 

   309     //Create the attachment and call its setFilename() method

   310     $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')

   311       ->setFilename('cool.jpg');

   312 

   313 

   314     //Because there's a fluid interface, you can do this in one statement

   315     $message->attach(

   316       Swift_Attachment::fromPath('/path/to/image.jpg')->setFilename('cool.jpg')

   317     );

   318 

   319 Attaching Dynamic Content

   320 ~~~~~~~~~~~~~~~~~~~~~~~~~

   321 

   322 Files that are generated at runtime, such as PDF documents or images created

   323 via GD can be attached directly to a message without writing them out to disk.

   324 Use the standard Swift_Attachment::newInstance() method.

   325 

   326 To attach dynamically created content:

   327 

   328 * Create your content as you normally would.

   329 

   330 * Create an attachment with ``Swift_Attachment::newInstance()``, specifying

   331   the source data of your content along with a name and the content-type.

   332 

   333 * Add the attachment to the message with ``attach()``.

   334 

   335 The attachment will be presented to the recipient as a downloadable file

   336 with the filename and content-type you specify.

   337 

   338 .. note::

   339 

   340     If you would usually write the file to disk anyway you should just attach

   341     it with ``Swift_Attachment::fromPath()`` since this will use less memory:

   342 

   343     .. code-block: php

   344 

   345         //Create your file contents in the normal way, but don't write them to disk

   346         $data = create_my_pdf_data();

   347 

   348         //Create the attachment with your data

   349         $attachment = Swift_Attachment::newInstance($data, 'my-file.pdf', 'application/pdf');  

   350 

   351         //Attach it to the message

   352         $message->attach($attachment);

   353 

   354 

   355         //You can alternatively use method chaining to build the attachment

   356         $attachment = Swift_Attachment::newInstance()

   357           ->setFilename('my-file.pdf')

   358           ->setContentType('application/pdf')

   359           ->setBody($data)

   360           ;

   361 

   362 Changing the Disposition

   363 ~~~~~~~~~~~~~~~~~~~~~~~~

   364 

   365 Attachments just appear as files that can be saved to the Desktop if desired.

   366 You can make attachment appear inline where possible by using the

   367 setDisposition() method of an attachment.

   368 

   369 To make an attachment appear inline:

   370 

   371 * Call its ``setDisposition()`` method.

   372 

   373 The attachment will be displayed within the email viewing window if the mail

   374 client knows how to display it.

   375 

   376 .. note::

   377 

   378     If you try to create an inline attachment for a non-displayable file type

   379     such as a ZIP file, the mail client should just present the attachment as

   380     normal:

   381 

   382     .. code-block:: php

   383 

   384         //Create the attachment and call its setDisposition() method

   385         $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')

   386           ->setDisposition('inline');

   387 

   388 

   389         //Because there's a fluid interface, you can do this in one statement

   390         $message->attach(

   391           Swift_Attachment::fromPath('/path/to/image.jpg')->setDisposition('inline')

   392         );

   393 

   394 Embedding Inline Media Files

   395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   396 

   397 Often people want to include an image or other content inline with a HTML

   398 message. It's easy to do this with HTML linking to remote resources, but this

   399 approach is usually blocked by mail clients. Swift Mailer allows you to embed

   400 your media directly into the message.

   401 

   402 Mail clients usually block downloads from remote resources because this

   403 technique was often abused as a mean of tracking who opened an email. If

   404 you're sending a HTML email and you want to include an image in the message

   405 another approach you can take is to embed the image directly.

   406 

   407 Swift Mailer makes embedding files into messages extremely streamlined. You

   408 embed a file by calling the ``embed()`` method of the message,

   409 which returns a value you can use in a ``src`` or

   410 ``href`` attribute in your HTML.

   411 

   412 Just like with attachments, it's possible to embed dynamically generated

   413 content without having an existing file available.

   414 

   415 The embedded files are sent in the email as a special type of attachment that

   416 has a unique ID used to reference them within your HTML attributes. On mail

   417 clients that do not support embedded files they may appear as attachments.

   418 

   419 Although this is commonly done for images, in theory it will work for any

   420 displayable (or playable) media type. Support for other media types (such as

   421 video) is dependent on the mail client however.

   422 

   423 Embedding Existing Files

   424 ........................

   425 

   426 Files that already exist, either on disk or at a URL can be embedded in a

   427 message with just one line of code, using Swift_EmbeddedFile::fromPath().

   428 

   429 You can embed files that exist locally, or if your PHP installation has

   430 ``allow_url_fopen`` turned on you can embed files from other

   431 websites.

   432 

   433 To embed an existing file:

   434 

   435 * Create a message object with ``Swift_Message::newInstance()``.

   436 

   437 * Set the body as HTML, and embed a file at the correct point in the message with ``embed()``.

   438 

   439 The file will be displayed with the message inline with the HTML wherever its ID

   440 is used as a ``src`` attribute.

   441 

   442 .. note::

   443 

   444     ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one

   445     another. ``Swift_Image`` exists for semantic purposes.

   446 

   447 .. note::

   448 

   449     You can embed files in two stages if you prefer. Just capture the return

   450     value of ``embed()`` in a variable and use that as the ``src`` attribute.

   451 

   452     .. code-block: php

   453 

   454         //Create the message

   455         $message = Swift_Message::newInstance('My subject');

   456 

   457         //Set the body

   458         $message->setBody(

   459         '<html>' .

   460         ' <head></head>' .

   461         ' <body>' .

   462         '  Here is an image <img src="' . //Embed the file

   463              $message->embed(Swift_Image::fromPath('image.png')) .

   464            '" alt="Image" />' .

   465         '  Rest of message' .

   466         ' </body>' .

   467         '</html>',

   468           'text/html' //Mark the content-type as HTML

   469         );

   470 

   471         //You can embed files from a URL if allow_url_fopen is on in php.ini

   472         $message->setBody(

   473         '<html>' .

   474         ' <head></head>' .

   475         ' <body>' .

   476         '  Here is an image <img src="' .

   477              $message->embed(Swift_Image::fromPath('http://site.tld/logo.png')) .

   478            '" alt="Image" />' .

   479         '  Rest of message' .

   480         ' </body>' .

   481         '</html>',

   482           'text/html'

   483         );

   484 

   485 

   486         // If placing the embed() code inline becomes cumbersome

   487         // it's easy to do this in two steps

   488         $cid = $message->embed(Swift_Image::fromPath('image.png'));

   489 

   490         $message->setBody(

   491         '<html>' .

   492         ' <head></head>' .

   493         ' <body>' .

   494         '  Here is an image <img src="' . $cid . '" alt="Image" />' .

   495         '  Rest of message' .

   496         ' </body>' .

   497         '</html>',

   498           'text/html' //Mark the content-type as HTML

   499         );

   500 

   501 Embedding Dynamic Content

   502 .........................

   503 

   504 Images that are generated at runtime, such as images created via GD can be

   505 embedded directly to a message without writing them out to disk. Use the

   506 standard Swift_Image::newInstance() method.

   507 

   508 To embed dynamically created content:

   509 

   510 * Create a message object with ``Swift_Message::newInstance()``.

   511 

   512 * Set the body as HTML, and embed a file at the correct point in the message

   513   with ``embed()``. You will need to specify a filename and a content-type.

   514 

   515 The file will be displayed with the message inline with the HTML wherever its ID

   516 is used as a ``src`` attribute.

   517 

   518 .. note::

   519 

   520     ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one

   521     another. ``Swift_Image`` exists for semantic purposes.

   522 

   523 .. note::

   524 

   525     You can embed files in two stages if you prefer. Just capture the return

   526     value of ``embed()`` in a variable and use that as the ``src`` attribute.

   527 

   528     .. code-block:: php

   529 

   530         //Create your file contents in the normal way, but don't write them to disk

   531         $img_data = create_my_image_data();

   532 

   533         //Create the message

   534         $message = Swift_Message::newInstance('My subject');

   535 

   536         //Set the body

   537         $message->setBody(

   538         '<html>' .

   539         ' <head></head>' .

   540         ' <body>' .

   541         '  Here is an image <img src="' . //Embed the file

   542              $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg')) .

   543            '" alt="Image" />' .

   544         '  Rest of message' .

   545         ' </body>' .

   546         '</html>',

   547           'text/html' //Mark the content-type as HTML

   548         );

   549 

   550 

   551         // If placing the embed() code inline becomes cumbersome

   552         // it's easy to do this in two steps

   553         $cid = $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg'));

   554 

   555         $message->setBody(

   556         '<html>' .

   557         ' <head></head>' .

   558         ' <body>' .

   559         '  Here is an image <img src="' . $cid . '" alt="Image" />' .

   560         '  Rest of message' .

   561         ' </body>' .

   562         '</html>',

   563           'text/html' //Mark the content-type as HTML

   564         );

   565 

   566 Adding Recipients to Your Message

   567 ---------------------------------

   568 

   569 Recipients are specified within the message itself via setTo(), setCc() and

   570 setBcc(). Swift Mailer reads these recipients from the message when it gets

   571 sent so that it knows where to send the message to.

   572 

   573 Message recipients are one of three types:

   574 

   575 * ``To:`` recipients -- the primary recipients (required)

   576 

   577 * ``Cc:`` recipients -- receive a copy of the message (optional)

   578 

   579 * ``Bcc:`` recipients -- hidden from other recipients (optional)

   580 

   581 Each type can contain one, or several addresses. It's possible to list only

   582 the addresses of the recipients, or you can personalize the address by

   583 providing the real name of the recipient.

   584 

   585 .. sidebar:: Syntax for Addresses

   586 

   587     If you only wish to refer to a single email address (for example your ``From:``

   588     address) then you can just use a string.

   589 

   590     .. code-block:: php

   591 

   592           $message->setFrom('some@address.tld');

   593 

   594     If you want to include a name then you must use an associative array.

   595 

   596     .. code-block:: php

   597 

   598          $message->setFrom(array('some@address.tld' => 'The Name'));

   599 

   600     If you want to include multiple addresses then you must use an array.

   601 

   602     .. code-block:: php

   603 

   604          $message->setTo(array('some@address.tld', 'other@address.tld'));

   605 

   606     You can mix personalized (addresses with a name) and non-personalized

   607     addresses in the same list by mixing the use of associative and non-associative

   608     array syntax.

   609 

   610     .. code-block:: php

   611 

   612          $message->setTo(array(

   613            'recipient-with-name@example.org' => 'Recipient Name One',

   614            'no-name@example.org', //Note that this is not a key-value pair

   615            'named-recipient@example.org' => 'Recipient Name Two'

   616          ));

   617 

   618 Setting ``To:`` Recipients

   619 ~~~~~~~~~~~~~~~~~~~~~~~~~~

   620 

   621 ``To:`` recipients are required in a message and are set with the

   622 ``setTo()`` or ``addTo()`` methods of the message.

   623 

   624 To set ``To:`` recipients, create the message object using either

   625 ``new Swift_Message( ... )`` or

   626 ``Swift_Message::newInstance( ... )``, then call the

   627 ``setTo()`` method with a complete array of addresses, or use the

   628 ``addTo()`` method to iteratively add recipients.

   629 

   630 The ``setTo()`` method accepts input in various formats as described earlier in

   631 this chapter. The ``addTo()`` method takes either one or two parameters. The

   632 first being the email address and the second optional parameter being the name

   633 of the recipient.

   634 

   635 ``To:`` recipients are visible in the message headers and will be

   636 seen by the other recipients.

   637 

   638 .. note::

   639 

   640     Multiple calls to ``setTo()`` will not add new recipients -- each

   641     call overrides the previous calls. If you want to iteratively add

   642     recipients, use the ``addTo()`` method.

   643 

   644     .. code-block:: php

   645 

   646         //Using setTo() to set all recipients in one go

   647         $message->setTo(array(

   648           'person1@example.org',

   649           'person2@otherdomain.org' => 'Person 2 Name',

   650           'person3@example.org',

   651           'person4@example.org',

   652           'person5@example.org' => 'Person 5 Name'

   653         ));

   654 

   655         //Using addTo() to add recipients iteratively

   656         $message->addTo('person1@example.org');

   657         $message->addTo('person2@example.org', 'Person 2 Name');

   658 

   659 Setting ``Cc:`` Recipients

   660 ~~~~~~~~~~~~~~~~~~~~~~~~~~

   661 

   662 ``Cc:`` recipients are set with the

   663 ``setCc()`` or ``addCc()`` methods of the message.

   664 

   665 To set ``Cc:`` recipients, create the message object using either

   666 ``new Swift_Message( ... )`` or

   667 ``Swift_Message::newInstance( ... )``, then call the

   668 ``setCc()`` method with a complete array of addresses, or use the

   669 ``addCc()`` method to iteratively add recipients.

   670 

   671 The ``setCc()`` method accepts input in various formats as described earlier in

   672 this chapter. The ``addCc()`` method takes either one or two parameters. The

   673 first being the email address and the second optional parameter being the name

   674 of the recipient.

   675 

   676 ``Cc:`` recipients are visible in the message headers and will be

   677 seen by the other recipients.

   678 

   679 .. note::

   680 

   681     Multiple calls to ``setCc()`` will not add new recipients -- each

   682     call overrides the previous calls. If you want to iteratively add Cc:

   683     recipients, use the ``addCc()`` method.

   684 

   685     .. code-block:: php

   686 

   687         //Using setCc() to set all recipients in one go

   688         $message->setCc(array(

   689           'person1@example.org',

   690           'person2@otherdomain.org' => 'Person 2 Name',

   691           'person3@example.org',

   692           'person4@example.org',

   693           'person5@example.org' => 'Person 5 Name'

   694         ));

   695 

   696         //Using addCc() to add recipients iteratively

   697         $message->addCc('person1@example.org');

   698         $message->addCc('person2@example.org', 'Person 2 Name');

   699 

   700 Setting ``Bcc:`` Recipients

   701 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

   702 

   703 ``Bcc:`` recipients receive a copy of the message without anybody

   704 else knowing it, and are set with the ``setBcc()`` or

   705 ``addBcc`` methods of the message.

   706 

   707 To set ``Bcc:`` recipients, create the message object using

   708 either ``new Swift_Message( ... )`` or

   709 ``Swift_Message::newInstance( ... )``, then call the

   710 ``setBcc()`` method with a complete array of addresses, or use

   711 the ``addBcc()`` method to iteratively add recipients.

   712 

   713 The ``setBcc()`` method accepts input in various formats as described earlier in

   714 this chapter. The ``addBcc()`` method takes either one or two parameters. The

   715 first being the email address and the second optional parameter being the name

   716 of the recipient.

   717 

   718 Only the individual ``Bcc:`` recipient will see their address in

   719 the message headers. Other recipients (including other ``Bcc:``

   720 recipients) will not see the address.

   721 

   722 .. note::

   723 

   724     Multiple calls to ``setBcc()`` will not add new recipients -- each

   725     call overrides the previous calls. If you want to iteratively add Bcc:

   726     recipients, use the ``addBcc()`` method.

   727 

   728     .. code-block:: php

   729 

   730         //Using setBcc() to set all recipients in one go

   731         $message->setBcc(array(

   732           'person1@example.org',

   733           'person2@otherdomain.org' => 'Person 2 Name',

   734           'person3@example.org',

   735           'person4@example.org',

   736           'person5@example.org' => 'Person 5 Name'

   737         ));

   738 

   739         //Using addBcc() to add recipients iteratively

   740         $message->addBcc('person1@example.org');

   741         $message->addBcc('person2@example.org', 'Person 2 Name');

   742 

   743 Specifying Sender Details

   744 -------------------------

   745 

   746 An email must include information about who sent it. Usually this is managed

   747 by the ``From:`` address, however there are other options.

   748 

   749 The sender information is contained in three possible places:

   750 

   751 * ``From:`` -- the address(es) of who wrote the message (required)

   752 

   753 * ``Sender:`` -- the address of the single person who sent the message

   754   (optional)

   755 

   756 * ``Return-Path:`` -- the address where bounces should go to (optional)

   757 

   758 You must always include a ``From:`` address by using

   759 ``setFrom()`` on the message. Swift Mailer will use this as the

   760 default ``Return-Path:`` unless otherwise specified.

   761 

   762 The ``Sender:`` address exists because the person who actually

   763 sent the email may not be the person who wrote the email. It has a higher

   764 precedence than the ``From:`` address and will be used as the

   765 ``Return-Path:`` unless otherwise specified.

   766 

   767 Setting the ``From:`` Address

   768 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   769 

   770 A ``From:`` address is required and is set with the

   771 ``setFrom()`` method of the message.

   772 

   773 ``From:`` addresses specify who actually wrote the email, and

   774 usually who sent it.

   775 

   776 What most people probably don't realise is that you can have more than one

   777 ``From:`` address if more than one person wrote the email --

   778 for example if an email was put together by a committee.

   779 

   780 To set the ``From:`` address(es):

   781 

   782 * Call the ``setFrom()`` method on the Message.

   783 

   784 The ``From:`` address(es) are visible in the message headers and

   785 will be seen by the recipients.

   786 

   787 .. note::

   788 

   789     If you set multiple ``From:`` addresses then you absolutely must set a

   790     ``Sender:`` address to indicate who physically sent the message.

   791 

   792     .. code-block:: php

   793 

   794         //Set a single From: address

   795         $message->setFrom('your@address.tld');

   796 

   797         //Set a From: address including a name

   798         $message->setFrom(array('your@address.tld' => 'Your Name'));

   799 

   800         //Set multiple From: addresses if multiple people wrote the email

   801         $message->setFrom(array(

   802           'person1@example.org' => 'Sender One',

   803           'person2@example.org' => 'Sender Two'

   804         ));

   805 

   806 Setting the ``Sender:`` Address

   807 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   808 

   809 A ``Sender:`` address specifies who sent the message and is set

   810 with the ``setSender()`` method of the message.

   811 

   812 To set the ``Sender:`` address:

   813 

   814 * Call the ``setSender()`` method on the Message.

   815 

   816 The ``Sender:`` address is visible in the message headers and

   817 will be seen by the recipients.

   818 

   819 This address will be used as the ``Return-Path:`` unless

   820 otherwise specified.

   821 

   822 .. note::

   823 

   824     If you set multiple ``From:`` addresses then you absolutely must set a

   825     ``Sender:`` address to indicate who physically sent the message.

   826 

   827 You must not set more than one sender address on a message because it's not

   828 possible for more than one person to send a single message.

   829 

   830 .. code-block:: php

   831 

   832     $message->setSender('your@address.tld');

   833 

   834 Setting the ``Return-Path:`` (Bounce) Address

   835 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   836 

   837 The ``Return-Path:`` address specifies where bounce notifications should

   838 be sent and is set with the ``setReturnPath()`` method of the message.

   839 

   840 You can only have one ``Return-Path:`` and it must not include

   841 a personal name.

   842 

   843 To set the ``Return-Path:`` address:

   844 

   845 * Call the ``setReturnPath()`` method on the Message.

   846 

   847 Bouce notifications will be sent to this address.

   848 

   849 .. code-block:: php

   850 

   851     $message->setReturnPath('bounces@address.tld');

   852 

   853 Requesting a Read Receipt

   854 -------------------------

   855 

   856 It is possible to request a read-receipt to be sent to an address when the

   857 email is opened. To request a read receipt set the address with

   858 ``setReadReceiptTo()``.

   859 

   860 To request a read receipt:

   861 

   862 * Set the address you want the receipt to be sent to with the

   863   ``setReadReceiptTo()`` method on the Message.

   864 

   865 When the email is opened, if the mail client supports it a notification will be sent to this address.

   866 

   867 .. note::

   868 

   869     Read receipts won't work for the majority of recipients since many mail

   870     clients auto-disable them. Those clients that will send a read receipt

   871     will make the user aware that one has been requested.

   872 

   873     .. code-block:: php

   874 

   875         $message->setReadReceiptTo('your@address.tld');

   876 

   877 Setting the Character Set

   878 -------------------------

   879 

   880 The character set of the message (and it's MIME parts) is set with the

   881 setCharset() method. You can also change the global default of UTF-8 by

   882 working with the Swift_Preferences class.

   883 

   884 Swift Mailer will default to the UTF-8 character set unless otherwise

   885 overridden. UTF-8 will work in most instances since it includes all of the

   886 standard US keyboard characters in addition to most international characters.

   887 

   888 It is absolutely vital however that you know what character set your message

   889 (or it's MIME parts) are written in otherwise your message may be received

   890 completely garbled.

   891 

   892 There are two places in Swift Mailer where you can change the character set:

   893 

   894 * In the Swift_Preferences class

   895 

   896 * On each individual message and/or MIME part

   897 

   898 To set the character set of your Message:

   899 

   900 * Change the global UTF-8 setting by calling

   901   ``Swift_Preferences::setCharset()``; or

   902 

   903 * Call the ``setCharset()`` method on the message or the MIME part.

   904 

   905    .. code-block:: php

   906 

   907     //Approach 1: Change the global setting (suggested)

   908     Swift_Preferences::getInstance()->setCharset('iso-8859-2');

   909 

   910     //Approach 2: Call the setCharset() method of the message

   911     $message = Swift_Message::newInstance()

   912       ->setCharset('iso-8859-2');

   913 

   914     //Apprach 3: Specify the charset when setting the body

   915     $message->setBody('My body', 'text/html', 'iso-8859-2');

   916 

   917     //Approach 4: Specify the charset for each part added

   918     $message->addPart('My part', 'text/plain', 'iso-8859-2');

   919 

   920 Setting the Line Length

   921 -----------------------

   922 

   923 The length of lines in a message can be changed by using the

   924 ``setMaxLineLength()`` method on the message. It should be kept

   925 to less than 1000 characters.

   926 

   927 Swift Mailer defaults to using 78 characters per line in a message. This is

   928 done for historical reasons and so that the message can be easily viewed in

   929 plain-text terminals.

   930 

   931 To change the maximum length of lines in your Message:

   932 

   933 * Call the ``setMaxLineLength()`` method on the Message.

   934 

   935 Lines that are longer than the line length specified will be wrapped between

   936 words.

   937 

   938 .. note::

   939 

   940     You should never set a maximum length longer than 1000 characters

   941     according to RFC 2822. Doing so could have unspecified side-effects such

   942     as truncating parts of your message when it is transported between SMTP

   943     servers.

   944 

   945     .. code-block:: php

   946 

   947         $message->setMaxLineLength(1000);

   948 

   949 Setting the Message Priority

   950 ----------------------------

   951 

   952 You can change the priority of the message with

   953 ``setPriority()``. Setting the priority will not change the way

   954 your email is sent -- it is purely an indicative setting for the

   955 recipient.

   956 

   957 The priority of a message is an indication to the recipient what significance

   958 it has. Swift Mailer allows you to set the priority by calling the

   959 ``setPriority`` method. This method takes an integer value

   960 between 1 and 5:

   961 

   962 * Highest

   963 * High

   964 * Normal

   965 * Low

   966 * Lowest

   967 

   968 To set the message priority:

   969 

   970 * Set the priority as an integer between 1 and 5 with the ``setPriority()``

   971   method on the Message.

   972 

   973 .. code-block:: php

   974 

   975     //Indicate "High" priority

   976     $message->setPriority(2);