swiftmailer/doc/headers.rst

Message Headers
===============

Sometimes you'll want to add your own headers to a message or modify/remove
headers that are already present. You work with the message's HeaderSet to do
this.

Header Basics
-------------

All MIME entities in Swift Mailer -- including the message itself -- store
their headers in a single object called a HeaderSet. This HeaderSet is
retrieved with the ``getHeaders()`` method.

As mentioned in the previous chapter, everything that forms a part of a message
in Swift Mailer is a MIME entity that is represented by an instance of
``Swift_Mime_SimpleMimeEntity``. This includes -- most notably -- the message
object itself, attachments, MIME parts and embedded images. Each of these MIME
entities consists of a body and a set of headers that describe the body.

For all of the "standard" headers in these MIME entities, such as the
``Content-Type``, there are named methods for working with them, such as
``setContentType()`` and ``getContentType()``. This is because headers are a
moderately complex area of the library. Each header has a slightly different
required structure that it must meet in order to comply with the standards that
govern email (and that are checked by spam blockers etc).

You fetch the HeaderSet from a MIME entity like so::

    $message = new Swift_Message();

    // Fetch the HeaderSet from a Message object
    $headers = $message->getHeaders();

    $attachment = Swift_Attachment::fromPath('document.pdf');

    // Fetch the HeaderSet from an attachment object
    $headers = $attachment->getHeaders();

The job of the HeaderSet is to contain and manage instances of Header objects.
Depending upon the MIME entity the HeaderSet came from, the contents of the
HeaderSet will be different, since an attachment for example has a different
set of headers to those in a message.

You can find out what the HeaderSet contains with a quick loop, dumping out the
names of the headers::

    foreach ($headers->getAll() as $header) {
      printf("%s<br />\n", $header->getFieldName());
    }

    /*
    Content-Transfer-Encoding
    Content-Type
    MIME-Version
    Date
    Message-ID
    From
    Subject
    To
    */

You can also dump out the rendered HeaderSet by calling its ``toString()``
method::

    echo $headers->toString();

    /*
    Message-ID: <1234869991.499a9ee7f1d5e@swift.generated>
    Date: Tue, 17 Feb 2009 22:26:31 +1100
    Subject: Awesome subject!
    From: sender@example.org
    To: recipient@example.org
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: quoted-printable
    */

Where the complexity comes in is when you want to modify an existing header.
This complexity comes from the fact that each header can be of a slightly
different type (such as a Date header, or a header that contains email
addresses, or a header that has key-value parameters on it!). Each header in
the HeaderSet is an instance of ``Swift_Mime_Header``. They all have common
functionality, but knowing exactly what type of header you're working with will
allow you a little more control.

You can determine the type of header by comparing the return value of its
``getFieldType()`` method with the constants ``TYPE_TEXT``,
``TYPE_PARAMETERIZED``, ``TYPE_DATE``, ``TYPE_MAILBOX``, ``TYPE_ID`` and
``TYPE_PATH`` which are defined in ``Swift_Mime_Header``::

    foreach ($headers->getAll() as $header) {
      switch ($header->getFieldType()) {
        case Swift_Mime_Header::TYPE_TEXT: $type = 'text';
          break;
        case Swift_Mime_Header::TYPE_PARAMETERIZED: $type = 'parameterized';
          break;
        case Swift_Mime_Header::TYPE_MAILBOX: $type = 'mailbox';
          break;
        case Swift_Mime_Header::TYPE_DATE: $type = 'date';
          break;
        case Swift_Mime_Header::TYPE_ID: $type = 'ID';
          break;
        case Swift_Mime_Header::TYPE_PATH: $type = 'path';
          break;
      }
      printf("%s: is a %s header<br />\n", $header->getFieldName(), $type);
    }

    /*
    Content-Transfer-Encoding: is a text header
    Content-Type: is a parameterized header
    MIME-Version: is a text header
    Date: is a date header
    Message-ID: is a ID header
    From: is a mailbox header
    Subject: is a text header
    To: is a mailbox header
    */

Headers can be removed from the set, modified within the set, or added to the
set.

The following sections show you how to work with the HeaderSet and explain the
details of each implementation of ``Swift_Mime_Header`` that may exist within
the HeaderSet.

Header Types
------------

Because all headers are modeled on different data (dates, addresses, text!)
there are different types of Header in Swift Mailer. Swift Mailer attempts to
categorize all possible MIME headers into more general groups, defined by a
small number of classes.

Text Headers
~~~~~~~~~~~~

Text headers are the simplest type of Header. They contain textual information
with no special information included within it -- for example the Subject
header in a message.

There's nothing particularly interesting about a text header, though it is
probably the one you'd opt to use if you need to add a custom header to a
message. It represents text just like you'd think it does. If the text contains
characters that are not permitted in a message header (such as new lines, or
non-ascii characters) then the header takes care of encoding the text so that
it can be used.

No header -- including text headers -- in Swift Mailer is vulnerable to
header-injection attacks. Swift Mailer breaks any attempt at header injection
by encoding the dangerous data into a non-dangerous form.

It's easy to add a new text header to a HeaderSet. You do this by calling the
HeaderSet's ``addTextHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addTextHeader('Your-Header-Name', 'the header value');

Changing the value of an existing text header is done by calling it's
``setValue()`` method::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('new subject');

When output via ``toString()``, a text header produces something like the
following::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('amazing subject line');
    echo $subject->toString();

    /*

    Subject: amazing subject line

    */

If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded. This is nothing to be concerned about since mail
clients will decode them back::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('contains – dash');
    echo $subject->toString();

    /*

    Subject: contains =?utf-8?Q?=E2=80=93?= dash

    */

Parameterized Headers
~~~~~~~~~~~~~~~~~~~~~

Parameterized headers are text headers that contain key-value parameters
following the textual content. The Content-Type header of a message is a
parameterized header since it contains charset information after the content
type.

The parameterized header type is a special type of text header. It extends the
text header by allowing additional information to follow it. All of the methods
from text headers are available in addition to the methods described here.

Adding a parameterized header to a HeaderSet is done by using the
``addParameterizedHeader()`` method which takes a text value like
``addTextHeader()`` but it also accepts an associative array of key-value
parameters::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addParameterizedHeader(
      'Header-Name', 'header value',
      ['foo' => 'bar']
      );

To change the text value of the header, call it's ``setValue()`` method just as
you do with text headers.

To change the parameters in the header, call the header's ``setParameters()``
method or the ``setParameter()`` method (note the pluralization)::

    $type = $message->getHeaders()->get('Content-Type');

    // setParameters() takes an associative array
    $type->setParameters([
      'name' => 'file.txt',
      'charset' => 'iso-8859-1'
    ]);

    // setParameter() takes two args for $key and $value
    $type->setParameter('charset', 'iso-8859-1');

When output via ``toString()``, a parameterized header produces something like
the following::

    $type = $message->getHeaders()->get('Content-Type');
    $type->setValue('text/html');
    $type->setParameter('charset', 'utf-8');

    echo $type->toString();

    /*

    Content-Type: text/html; charset=utf-8

    */

If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded, just like they are for text headers. This is
nothing to be concerned about since mail clients will decode them back.
Likewise, if the parameters contain any non-ascii characters they will be
encoded so that they can be transmitted safely::

    $attachment = new Swift_Attachment();
    $disp = $attachment->getHeaders()->get('Content-Disposition');
    $disp->setValue('attachment');
    $disp->setParameter('filename', 'report–may.pdf');
    echo $disp->toString();

    /*

    Content-Disposition: attachment; filename*=utf-8''report%E2%80%93may.pdf

    */

Date Headers
~~~~~~~~~~~~

Date headers contains an RFC 2822 formatted date (i.e. what PHP's ``date('r')``
returns). They are used anywhere a date or time is needed to be presented as a
message header.

The data on which a date header is modeled as a DateTimeImmutable object. The
object is used to create a correctly structured RFC 2822 formatted date with
timezone such as ``Tue, 17 Feb 2009 22:26:31 +1100``.

The obvious place this header type is used is in the ``Date:`` header of the
message itself.

It's easy to add a new date header to a HeaderSet. You do this by calling the
HeaderSet's ``addDateHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addDateHeader('Your-Header', new DateTimeImmutable('3 days ago'));

Changing the value of an existing date header is done by calling it's
``setDateTime()`` method::

    $date = $message->getHeaders()->get('Date');
    $date->setDateTime(new DateTimeImmutable());

When output via ``toString()``, a date header produces something like the
following::

    $date = $message->getHeaders()->get('Date');
    echo $date->toString();

    /*

    Date: Wed, 18 Feb 2009 13:35:02 +1100

    */

Mailbox (e-mail address) Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mailbox headers contain one or more email addresses, possibly with personalized
names attached to them. The data on which they are modeled is represented by an
associative array of email addresses and names.

Mailbox headers are probably the most complex header type to understand in
Swift Mailer because they accept their input as an array which can take various
forms, as described in the previous chapter.

All of the headers that contain e-mail addresses in a message -- with the
exception of ``Return-Path:`` which has a stricter syntax -- use this header
type. That is, ``To:``, ``From:`` etc.

You add a new mailbox header to a HeaderSet by calling the HeaderSet's
``addMailboxHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addMailboxHeader('Your-Header-Name', [
          'person1@example.org' => 'Person Name One',
          'person2@example.org',
          'person3@example.org',
          'person4@example.org' => 'Another named person'
    ]);

Changing the value of an existing mailbox header is done by calling it's
``setNameAddresses()`` method::

    $to = $message->getHeaders()->get('To');
    $to->setNameAddresses([
      'joe@example.org' => 'Joe Bloggs',
      'john@example.org' => 'John Doe',
      'no-name@example.org'
    ]);

If you don't wish to concern yourself with the complicated accepted input
formats accepted by ``setNameAddresses()`` as described in the previous chapter
and you only want to set one or more addresses (not names) then you can just
use the ``setAddresses()`` method instead::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses([
      'joe@example.org',
      'john@example.org',
      'no-name@example.org'
    ]);

.. note::

    Both methods will accept the above input format in practice.

If all you want to do is set a single address in the header, you can use a
string as the input parameter to ``setAddresses()`` and/or
``setNameAddresses()``::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses('joe-bloggs@example.org');

When output via ``toString()``, a mailbox header produces something like the
following::

    $to = $message->getHeaders()->get('To');
    $to->setNameAddresses([
      'person1@example.org' => 'Name of Person',
      'person2@example.org',
      'person3@example.org' => 'Another Person'
    ]);

    echo $to->toString();

    /*

    To: Name of Person <person1@example.org>, person2@example.org, Another Person
     <person3@example.org>

    */

Internationalized domains are automatically converted to IDN encoding::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses('joe@ëxämple.org');

    echo $to->toString();

    /*

    To: joe@xn--xmple-gra1c.org

    */

ID Headers
~~~~~~~~~~

ID headers contain identifiers for the entity (or the message). The most
notable ID header is the Message-ID header on the message itself.

An ID that exists inside an ID header looks more-or-less less like an email
address. For example, ``<1234955437.499becad62ec2@example.org>``. The part to
the left of the @ sign is usually unique, based on the current time and some
random factor. The part on the right is usually a domain name.

Any ID passed to the header's ``setId()`` method absolutely MUST conform to
this structure, otherwise you'll get an Exception thrown at you by Swift Mailer
(a ``Swift_RfcComplianceException``). This is to ensure that the generated
email complies with relevant RFC documents and therefore is less likely to be
blocked as spam.

It's easy to add a new ID header to a HeaderSet. You do this by calling the
HeaderSet's ``addIdHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addIdHeader('Your-Header-Name', '123456.unqiue@example.org');

Changing the value of an existing ID header is done by calling its ``setId()``
method::

    $msgId = $message->getHeaders()->get('Message-ID');
    $msgId->setId(time() . '.' . uniqid('thing') . '@example.org');

When output via ``toString()``, an ID header produces something like the
following::

    $msgId = $message->getHeaders()->get('Message-ID');
    echo $msgId->toString();

    /*

    Message-ID: <1234955437.499becad62ec2@example.org>

    */

Path Headers
~~~~~~~~~~~~

Path headers are like very-restricted mailbox headers. They contain a single
email address with no associated name. The Return-Path header of a message is a
path header.

You add a new path header to a HeaderSet by calling the HeaderSet's
``addPathHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addPathHeader('Your-Header-Name', 'person@example.org');

Changing the value of an existing path header is done by calling its
``setAddress()`` method::

    $return = $message->getHeaders()->get('Return-Path');
    $return->setAddress('my-address@example.org');

When output via ``toString()``, a path header produces something like the
following::

    $return = $message->getHeaders()->get('Return-Path');
    $return->setAddress('person@example.org');
    echo $return->toString();

    /*

    Return-Path: <person@example.org>

    */

Header Operations
-----------------

Working with the headers in a message involves knowing how to use the methods
on the HeaderSet and on the individual Headers within the HeaderSet.

Adding new Headers
~~~~~~~~~~~~~~~~~~

New headers can be added to the HeaderSet by using one of the provided
``add..Header()`` methods.

The added header will appear in the message when it is sent::

    // Adding a custom header to a message
    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addTextHeader('X-Mine', 'something here');

    // Adding a custom header to an attachment
    $attachment = Swift_Attachment::fromPath('/path/to/doc.pdf');
    $attachment->getHeaders()->addDateHeader('X-Created-Time', time());

Retrieving Headers
~~~~~~~~~~~~~~~~~~

Headers are retrieved through the HeaderSet's ``get()`` and ``getAll()``
methods::

    $headers = $message->getHeaders();

    // Get the To: header
    $toHeader = $headers->get('To');

    // Get all headers named "X-Foo"
    $fooHeaders = $headers->getAll('X-Foo');

    // Get the second header named "X-Foo"
    $foo = $headers->get('X-Foo', 1);

    // Get all headers that are present
    $all = $headers->getAll();

When using ``get()`` a single header is returned that matches the name (case
insensitive) that is passed to it. When using ``getAll()`` with a header name,
an array of headers with that name are returned. Calling ``getAll()`` with no
arguments returns an array of all headers present in the entity.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``getAll()`` exists to fetch all
    headers with a specified name. In addition, ``get()`` accepts an optional
    numerical index, starting from zero to specify which header you want more
    specifically.

.. note::

    If you want to modify the contents of the header and you don't know for
    sure what type of header it is then you may need to check the type by
    calling its ``getFieldType()`` method.

Check if a Header Exists
~~~~~~~~~~~~~~~~~~~~~~~~

You can check if a named header is present in a HeaderSet by calling its
``has()`` method::

    $headers = $message->getHeaders();

    // Check if the To: header exists
    if ($headers->has('To')) {
      echo 'To: exists';
    }

    // Check if an X-Foo header exists twice (i.e. check for the 2nd one)
    if ($headers->has('X-Foo', 1)) {
      echo 'Second X-Foo header exists';
    }

If the header exists, ``true`` will be returned or ``false`` if not.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``has()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically.

Removing Headers
~~~~~~~~~~~~~~~~

Removing a Header from the HeaderSet is done by calling the HeaderSet's
``remove()`` or ``removeAll()`` methods::

    $headers = $message->getHeaders();

    // Remove the Subject: header
    $headers->remove('Subject');

    // Remove all X-Foo headers
    $headers->removeAll('X-Foo');

    // Remove only the second X-Foo header
    $headers->remove('X-Foo', 1);

When calling ``remove()`` a single header will be removed. When calling
``removeAll()`` all headers with the given name will be removed. If no headers
exist with the given name, no errors will occur.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``remove()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically. For the same reason, ``removeAll()`` exists to
    remove all headers that have the given name.

Modifying a Header's Content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To change a Header's content you should know what type of header it is and then
call it's appropriate setter method. All headers also have a
``setFieldBodyModel()`` method that accepts a mixed parameter and delegates to
the correct setter::

The header will be updated inside the HeaderSet and the changes will be seen
when the message is sent::

    $headers = $message->getHeaders();

    // Change the Subject: header
    $subj = $headers->get('Subject');
    $subj->setValue('new subject here');

    // Change the To: header
    $to = $headers->get('To');
    $to->setNameAddresses([
      'person@example.org' => 'Person',
      'thing@example.org'
    ]);

    // Using the setFieldBodyModel() just delegates to the correct method
    // So here to calls setNameAddresses()
    $to->setFieldBodyModel([
      'person@example.org' => 'Person',
      'thing@example.org'
    ]);