Class Mail::Header
In: lib/mail/header.rb
Parent: Object

Provides access to a header object.

Per RFC2822

 2.2. Header Fields

  Header fields are lines composed of a field name, followed by a colon
  (":"), followed by a field body, and terminated by CRLF.  A field
  name MUST be composed of printable US-ASCII characters (i.e.,
  characters that have values between 33 and 126, inclusive), except
  colon.  A field body may be composed of any US-ASCII characters,
  except for CR and LF.  However, a field body may contain CRLF when
  used in header "folding" and  "unfolding" as described in section
  2.2.3.  All field bodies MUST conform to the syntax described in
  sections 3 and 4 of this standard.

Methods

Included Modules

Patterns Utilities Enumerable

Constants

LIMITED_FIELDS = %w[ orig-date from sender reply-to to cc bcc message-id in-reply-to references subject return-path content-type mime-version content-transfer-encoding content-description content-id content-disposition content-location]

Public Class methods

Creates a new header object.

Accepts raw text or nothing. If given raw text will attempt to parse it and split it into the various fields, instantiating each field as it goes.

If it finds a field that should be a structured field (such as content type), but it fails to parse it, it will simply make it an unstructured field and leave it alone. This will mean that the data is preserved but no automatic processing of that field will happen. If you find one of these cases, please make a patch and send it in, or at the least, send me the example so we can fix it.

Public Instance methods

 3.6. Field definitions

  The following table indicates limits on the number of times each
  field may occur in a message header as well as any special
  limitations on the use of those fields.  An asterisk next to a value
  in the minimum or maximum column indicates that a special restriction
  appears in the Notes column.

  <snip table from 3.6>

As per RFC, many fields can appear more than once, we will return a string of the value if there is only one header, or if there is more than one matching header, will return an array of values in order that they appear in the header ordered from top to bottom.

Example:

 h = Header.new
 h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
 h['To']          #=> 'mikel@me.com'
 h['X-Mail-SPAM'] #=> ['15', '20']

Sets the FIRST matching field in the header to passed value, or deletes the FIRST field matched from the header if passed nil

Example:

 h = Header.new
 h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
 h['To'] = 'bob@you.com'
 h['To']    #=> 'bob@you.com'
 h['X-Mail-SPAM'] = '10000'
 h['X-Mail-SPAM'] # => ['15', '20', '10000']
 h['X-Mail-SPAM'] = nil
 h['X-Mail-SPAM'] # => nil

Returns an array of all the fields in the header in order that they were read in.

 3.6. Field definitions

  It is important to note that the header fields are not guaranteed to
  be in a particular order.  They may appear in any order, and they
  have been known to be reordered occasionally when transported over
  the Internet.  However, for the purposes of this standard, header
  fields SHOULD NOT be reordered when a message is transported or
  transformed.  More importantly, the trace header fields and resent
  header fields MUST NOT be reordered, and SHOULD be kept in blocks
  prepended to the message.  See sections 3.6.6 and 3.6.7 for more
  information.

Populates the fields container with Field objects in the order it receives them in.

Acceps an array of field string values, for example:

 h = Header.new
 h.fields = ['From: mikel@me.com', 'To: bob@you.com']

Returns true if the header has a Content-ID defined (empty or not)

Returns true if the header has a Date defined (empty or not)

Returns true if the header has a Message-ID defined (empty or not)

Returns true if the header has a message_id defined (empty or not)

The preserved raw source of the header as you passed it in, untouched for your Regexing glory.

[Validate]