Class: Mail::Header

### Home Classes Methods

### In Files

- lib/mail/header.rb

### Parent

Object

### Methods

- ::new
- #[]
- #[]=
- #charset
- #charset=
- #decoded
- #encoded
- #errors
- #field_summary
- #fields
- #fields=
- #has_content_id?
- #has_date?
- #has_message_id?
- #has_mime_version?
- #raw_source
- #to_s

### Included Modules

- Mail::Patterns
- Mail::Utilities
- Enumerable

### Files

- TODO.rdoc
- VERSION

### Class/Module Index

Quicksearch

- Mail
- Mail::Address
- Mail::AddressContainer
- Mail::AddressLists
- Mail::AddressLists::PrimaryAddress0
- Mail::AddressLists::PrimaryAddress1
- Mail::AddressListsParser
- Mail::AttachmentsList
- Mail::BccField
- Mail::Body
- Mail::CcField
- Mail::CommentsField
- Mail::ContentDescriptionField
- Mail::ContentDisposition
- Mail::ContentDisposition::ContentDisposition0
- Mail::ContentDisposition::ContentDisposition1
- Mail::ContentDisposition::ContentDisposition2
- Mail::ContentDisposition::DispositionType0
- Mail::ContentDisposition::DispositionType1
- Mail::ContentDisposition::Parameter0
- Mail::ContentDisposition::Parameter1
- Mail::ContentDisposition::Value0
- Mail::ContentDispositionField
- Mail::ContentDispositionParser
- Mail::ContentIdField
- Mail::ContentLocation
- Mail::ContentLocation::Location0
- Mail::ContentLocation::Primary0
- Mail::ContentLocationField
- Mail::ContentLocationParser
- Mail::ContentTransferEncoding
- Mail::ContentTransferEncoding::Encoding0
- Mail::ContentTransferEncoding::Encoding1
- Mail::ContentTransferEncoding::Primary0
- Mail::ContentTransferEncodingElement
- Mail::ContentTransferEncodingField
- Mail::ContentTransferEncodingParser
- Mail::ContentType
- Mail::ContentType::CompositeType0
- Mail::ContentType::CompositeType1
- Mail::ContentType::ContentType0
- Mail::ContentType::ContentType1
- Mail::ContentType::ContentType2
- Mail::ContentType::DiscreteType0
- Mail::ContentType::DiscreteType1
- Mail::ContentType::DiscreteType2
- Mail::ContentType::DiscreteType3
- Mail::ContentType::DiscreteType4
- Mail::ContentType::Parameter0
- Mail::ContentType::Parameter1
- Mail::ContentType::Value0
- Mail::ContentTypeField
- Mail::ContentTypeParser
- Mail::DateField
- Mail::DateTime
- Mail::DateTime::Primary0
- Mail::DateTime::Primary1
- Mail::DateTimeParser
- Mail::Encodings
- Mail::Encodings::Base64
- Mail::Encodings::Binary
- Mail::Encodings::EightBit
- Mail::Encodings::QuotedPrintable
- Mail::Encodings::SevenBit
- Mail::Encodings::TransferEncoding
- Mail::Envelope
- Mail::EnvelopeFrom
- Mail::EnvelopeFrom::CtimeDate0
- Mail::EnvelopeFrom::Primary0
- Mail::EnvelopeFromElement
- Mail::EnvelopeFromParser
- Mail::Exim
- Mail::Field
- Mail::Field::FieldError
- Mail::FieldList
- Mail::FileDelivery
- Mail::FromField
- Mail::Header
- Mail::IMAP
- Mail::InReplyToField
- Mail::IndifferentHash
- Mail::KeywordsField
- Mail::Matchers
- Mail::Matchers::HasSentEmailMatcher
- Mail::MessageIdField
- Mail::MessageIds
- Mail::MessageIds::Primary0
- Mail::MessageIdsElement
- Mail::MessageIdsParser
- Mail::MimeVersion
- Mail::MimeVersion::Version0
- Mail::MimeVersion::Version1
- Mail::MimeVersionElement
- Mail::MimeVersionField
- Mail::MimeVersionParser
- Mail::Multibyte
- Mail::Multibyte::EncodingError
- Mail::OptionalField
- Mail::POP3
- Mail::ParameterHash
- Mail::Part
- Mail::PartsList
- Mail::Patterns
- Mail::PhraseList
- Mail::PhraseLists
- Mail::PhraseLists::PrimaryPhrase0
- Mail::PhraseListsParser
- Mail::RFC2045
- Mail::RFC2045::CustomXToken0
- Mail::RFC2045Parser
- Mail::RFC2822
- Mail::RFC2822::AddrSpec0
- Mail::RFC2822::Address0
- Mail::RFC2822::Address1
- Mail::RFC2822::AddressList0
- Mail::RFC2822::AddressList1
- Mail::RFC2822::AngleAddr0
- Mail::RFC2822::Atom0
- Mail::RFC2822::CFWS0
- Mail::RFC2822::CFWS1
- Mail::RFC2822::Comment0
- Mail::RFC2822::Comment1
- Mail::RFC2822::Date0
- Mail::RFC2822::DateTime0
- Mail::RFC2822::DateTime1
- Mail::RFC2822::Day0
- Mail::RFC2822::DayOfWeek0
- Mail::RFC2822::DomainLiteral0
- Mail::RFC2822::DomainLiteral1
- Mail::RFC2822::DomainText0
- Mail::RFC2822::DomainText1
- Mail::RFC2822::DotAtom0
- Mail::RFC2822::DotAtomText0
- Mail::RFC2822::FWS0
- Mail::RFC2822::FWS1
- Mail::RFC2822::Group0
- Mail::RFC2822::Hour0
- Mail::RFC2822::ItemName0
- Mail::RFC2822::ItemName1
- Mail::RFC2822::LocalDotAtom0
- Mail::RFC2822::LocalDotAtomText0
- Mail::RFC2822::MailboxList0
- Mail::RFC2822::MailboxList1
- Mail::RFC2822::MailboxListGroup0
- Mail::RFC2822::MessageIds0
- Mail::RFC2822::MessageIds1
- Mail::RFC2822::Minute0
- Mail::RFC2822::Month0
- Mail::RFC2822::MsgId0
- Mail::RFC2822::MsgIdDomainText0
- Mail::RFC2822::MsgIdDomainText1
- Mail::RFC2822::MsgIdDotAtomText0
- Mail::RFC2822::MsgIdValue0
- Mail::RFC2822::NameAddr0
- Mail::RFC2822::NameValList0
- Mail::RFC2822::NameValList1
- Mail::RFC2822::NameValList2
- Mail::RFC2822::NameValPair0
- Mail::RFC2822::NoFoldLiteral0
- Mail::RFC2822::NoFoldQuote0
- Mail::RFC2822::Path0
- Mail::RFC2822::PhraseList0
- Mail::RFC2822::PhraseList1
- Mail::RFC2822::QuotedDomain0
- Mail::RFC2822::QuotedPair0
- Mail::RFC2822::QuotedString0
- Mail::RFC2822::QuotedString1
- Mail::RFC2822::Received0
- Mail::RFC2822::Return0
- Mail::RFC2822::Second0
- Mail::RFC2822::Time0
- Mail::RFC2822::TimeOfDay0
- Mail::RFC2822::TimeOfDay1
- Mail::RFC2822::Year0
- Mail::RFC2822::Zone0
- Mail::RFC2822Obsolete
- Mail::RFC2822Obsolete::ObsAddrList0
- Mail::RFC2822Obsolete::ObsAddrList1
- Mail::RFC2822Obsolete::ObsAngleAddr0
- Mail::RFC2822Obsolete::ObsBcc0
- Mail::RFC2822Obsolete::ObsCc0
- Mail::RFC2822Obsolete::ObsComments0
- Mail::RFC2822Obsolete::ObsDay0
- Mail::RFC2822Obsolete::ObsDay1
- Mail::RFC2822Obsolete::ObsDayOfWeek0
- Mail::RFC2822Obsolete::ObsDomain0
- Mail::RFC2822Obsolete::ObsDomain1
- Mail::RFC2822Obsolete::ObsDomainList0
- Mail::RFC2822Obsolete::ObsDomainList1
- Mail::RFC2822Obsolete::ObsFWS0
- Mail::RFC2822Obsolete::ObsFWS1
- Mail::RFC2822Obsolete::ObsFrom0
- Mail::RFC2822Obsolete::ObsHour0
- Mail::RFC2822Obsolete::ObsHour1
- Mail::RFC2822Obsolete::ObsInReplyTo0
- Mail::RFC2822Obsolete::ObsKeywords0
- Mail::RFC2822Obsolete::ObsLocalPart0
- Mail::RFC2822Obsolete::ObsLocalPart1
- Mail::RFC2822Obsolete::ObsMboxList0
- Mail::RFC2822Obsolete::ObsMboxList1
- Mail::RFC2822Obsolete::ObsMessageId0
- Mail::RFC2822Obsolete::ObsMinute0
- Mail::RFC2822Obsolete::ObsMinute1
- Mail::RFC2822Obsolete::ObsMonth0
- Mail::RFC2822Obsolete::ObsOptional0
- Mail::RFC2822Obsolete::ObsOrigDate0
- Mail::RFC2822Obsolete::ObsPhraseList0
- Mail::RFC2822Obsolete::ObsPhraseList1
- Mail::RFC2822Obsolete::ObsQp0
- Mail::RFC2822Obsolete::ObsReceived0
- Mail::RFC2822Obsolete::ObsReferences0
- Mail::RFC2822Obsolete::ObsReplyTo0
- Mail::RFC2822Obsolete::ObsResentBcc0
- Mail::RFC2822Obsolete::ObsResentCc0
- Mail::RFC2822Obsolete::ObsResentDate0
- Mail::RFC2822Obsolete::ObsResentFrom0
- Mail::RFC2822Obsolete::ObsResentMid0
- Mail::RFC2822Obsolete::ObsResentRply0
- Mail::RFC2822Obsolete::ObsResentSend0
- Mail::RFC2822Obsolete::ObsResentTo0
- Mail::RFC2822Obsolete::ObsReturn0
- Mail::RFC2822Obsolete::ObsRoute0
- Mail::RFC2822Obsolete::ObsSecond0
- Mail::RFC2822Obsolete::ObsSecond1
- Mail::RFC2822Obsolete::ObsSender0
- Mail::RFC2822Obsolete::ObsSubject0
- Mail::RFC2822Obsolete::ObsText0
- Mail::RFC2822Obsolete::ObsText1
- Mail::RFC2822Obsolete::ObsTo0
- Mail::RFC2822Obsolete::ObsYear0
- Mail::RFC2822Obsolete::ObsYear1
- Mail::RFC2822ObsoleteParser
- Mail::RFC2822Parser
- Mail::Received
- Mail::Received::Primary0
- Mail::ReceivedElement
- Mail::ReceivedField
- Mail::ReceivedParser
- Mail::ReferencesField
- Mail::ReplyToField
- Mail::ResentBccField
- Mail::ResentCcField
- Mail::ResentDateField
- Mail::ResentFromField
- Mail::ResentMessageIdField
- Mail::ResentSenderField
- Mail::ResentToField
- Mail::Retriever
- Mail::ReturnPathField
- Mail::Ruby18
- Mail::Ruby19
- Mail::RubyVer
- Mail::SMTP
- Mail::SMTPConnection
- Mail::SenderField
- Mail::Sendmail
- Mail::ShellEscape
- Mail::StructuredField
- Mail::SubjectField
- Mail::TestMailer
- Mail::TestRetriever
- Mail::ToField
- Mail::UnstructuredField
- Mail::Utilities
- Mail::VERSION
- Net
- Net::SMTP
- Object
- String

No matching classes.

# Mail::Header

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.

### Constants

LIMITED_FIELDS

### Public Class Methods

new(header_text = nil, charset = nil) click to toggle source

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.

    # File lib/mail/header.rb, line 35
    def initialize(header_text = nil, charset = nil)
      @errors = []
      @charset = charset
      self.raw_source = header_text.to_crlf
      split_header if header_text
    end

### Public Instance Methods

[](name) click to toggle source

    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']

    # File lib/mail/header.rb, line 116
    def [](name)
      name = dasherize(name).downcase
      selected = select_field_for(name)
      case
      when selected.length > 1
        selected.map { |f| f }
      when !selected.blank?
        selected.first
      else
        nil
      end
    end

[]=(name, value) click to toggle source

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

    # File lib/mail/header.rb, line 142
    def []=(name, value)
      name = dasherize(name)
      fn = name.downcase
      selected = select_field_for(fn)

      case
      # User wants to delete the field
      when !selected.blank? && value == nil
        fields.delete_if { |f| selected.include?(f) }

      # User wants to change the field
      when !selected.blank? && limited_field?(fn)
        selected.first.update(fn, value)

      # User wants to create the field
      else
        # Need to insert in correct order for trace fields
        self.fields << Field.new(name.to_s, value, charset)
      end
    end

charset() click to toggle source

    # File lib/mail/header.rb, line 163
    def charset
      params = self[:content_type].parameters rescue nil
      if params
        params[:charset]
      else
        @charset
      end
    end

charset=(val) click to toggle source

    # File lib/mail/header.rb, line 172
    def charset=(val)
      params = self[:content_type].parameters rescue nil
      if params
        params[:charset] = val
      end
      @charset = val
    end

decoded() click to toggle source

    # File lib/mail/header.rb, line 198
    def decoded
      raise NoMethodError, 'Can not decode an entire header as there could be character set conflicts, try calling #decoded on the various fields.'
    end

encoded() click to toggle source

    # File lib/mail/header.rb, line 186
    def encoded
      buffer = ''
      fields.each do |field|
        buffer << field.encoded
      end
      buffer
    end

errors() click to toggle source

    # File lib/mail/header.rb, line 91
    def errors
      @errors
    end

field_summary() click to toggle source

    # File lib/mail/header.rb, line 202
    def field_summary
      fields.map { |f| "<#{f.name}: #{f.value}>" }.join(", ")
    end

fields() click to toggle source

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

    # File lib/mail/header.rb, line 50
    def fields
      @fields ||= FieldList.new
    end

fields=(unfolded_fields) click to toggle source

    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']

    # File lib/mail/header.rb, line 73
    def fields=(unfolded_fields)
      @fields = Mail::FieldList.new
      warn "Warning: more than 1000 header fields only using the first 1000" if unfolded_fields.length > 1000
      unfolded_fields[0..1000].each do |field|

        field = Field.new(field, nil, charset)
        field.errors.each { |error| self.errors << error }
        selected = select_field_for(field.name)

        if selected.any? && limited_field?(field.name)
          selected.first.update(field.name, field.value)
        else
          @fields << field
        end
      end

    end

has_content_id?() click to toggle source

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

    # File lib/mail/header.rb, line 212
    def has_content_id?
      !fields.select { |f| f.responsible_for?('Content-ID') }.empty?
    end

has_date?() click to toggle source

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

    # File lib/mail/header.rb, line 217
    def has_date?
      !fields.select { |f| f.responsible_for?('Date') }.empty?
    end

has_message_id?() click to toggle source

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

    # File lib/mail/header.rb, line 207
    def has_message_id?
      !fields.select { |f| f.responsible_for?('Message-ID') }.empty?
    end

has_mime_version?() click to toggle source

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

    # File lib/mail/header.rb, line 222
    def has_mime_version?
      !fields.select { |f| f.responsible_for?('Mime-Version') }.empty?
    end

raw_source() click to toggle source

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

    # File lib/mail/header.rb, line 44
    def raw_source
      @raw_source
    end

to_s() click to toggle source

    # File lib/mail/header.rb, line 194
    def to_s
      encoded
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.