class Mail::Message

# File lib/mail/message.rb, line 107
def initialize(*args, &block)
  @body = nil
  @body_raw = nil
  @separate_parts = false
  @text_part = nil
  @html_part = nil
  @errors = nil
  @header = nil
  @charset = self.class.default_charset
  @defaulted_charset = true

  @smtp_envelope_from = nil
  @smtp_envelope_to = nil

  @perform_deliveries = true
  @raise_delivery_errors = true

  @delivery_handler = nil

  @delivery_method = Mail.delivery_method.dup

  @transport_encoding = Mail::Encodings.get_encoding('7bit')

  @mark_for_delete = false

  if args.flatten.first.respond_to?(:each_pair)
    init_with_hash(args.flatten.first)
  else
    init_with_string(args.flatten[0].to_s)
  end

  # Support both builder styles:
  #
  #   Mail.new do
  #     to 'recipient@example.com'
  #   end
  #
  # and
  #
  #   Mail.new do |m|
  #     m.to 'recipient@example.com'
  #   end
  if block_given?
    if block.arity.zero?
      instance_eval(&block)
    else
      yield self
    end
  end

  self
end

Making an email¶ ↑

You can make an new mail object via a block, passing a string, file or direct assignment.

Making an email via a block¶ ↑

mail = Mail.new do |m|
  m.from 'mikel@test.lindsaar.net'
  m.to 'you@test.lindsaar.net'
  m.subject 'This is a test email'
  m.body File.read('body.txt')
end

mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...

If may also pass a block with no arguments, in which case it will be evaluated in the scope of the new message instance:

mail = Mail.new do
  from 'mikel@test.lindsaar.net'
  # …
end

Making an email via passing a string¶ ↑

mail = Mail.new("To: mikel@test.lindsaar.net\r\nSubject: Hello\r\n\r\nHi there!")
mail.body.to_s #=> 'Hi there!'
mail.subject   #=> 'Hello'
mail.to        #=> 'mikel@test.lindsaar.net'

Making an email from a file¶ ↑

mail = Mail.read('path/to/file.eml')
mail.body.to_s #=> 'Hi there!'
mail.subject   #=> 'Hello'
mail.to        #=> 'mikel@test.lindsaar.net'

Making an email via assignment¶ ↑

You can assign values to a mail object via four approaches:

• Message#field_name=(value)

• Message#field_name(value)

• Message#=(value)

• Message#=(value)

Examples:

mail = Mail.new
mail['from'] = 'mikel@test.lindsaar.net'
mail[:to]    = 'you@test.lindsaar.net'
mail.subject 'This is a test email'
mail.body    = 'This is a body'

mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...

# File lib/mail/message.rb, line 334
def <=>(other)
  if other.nil?
    1
  else
    self.date <=> other.date
  end
end

Provides the operator needed for sort et al.

Compares this mail object with another mail object, this is done by date, so an email that is older than another will appear first.

Example:

mail1 = Mail.new do
  date(Time.now)
end
mail2 = Mail.new do
  date(Time.now - 86400) # 1 day older
end
[mail2, mail1].sort #=> [mail2, mail1]

# File lib/mail/message.rb, line 377
def ==(other) # TODO could be more efficient
  return false unless other.respond_to?(:encoded)

  stamp = Mail::CommonDateField.normalize_datetime('')
  # Note: must always dup the inputs so they are not altered by encoded
  if self.message_id && other.message_id
    dup.tap { |m| m.date ||= stamp }.encoded ==
      other.dup.tap { |m| m.date ||= stamp }.encoded
  else
    dup.tap { |m| m.message_id = '<temp@test>'; m.date ||= stamp }.encoded ==
      other.dup.tap { |m| m.message_id = '<temp@test>'; m.date ||= stamp }.encoded
  end
end

Two emails are the same if they have the same fields and body contents. One gotcha here is that Mail will insert Message-IDs when calling encoded, so doing mail1.encoded == mail2.encoded is most probably not going to return what you think as the assigned Message-IDs by Mail (if not already defined as the same) will ensure that the two objects are unique, and this comparison will ALWAYS return false.

So the == operator has been defined like so: Two messages are the same if they have the same content, ignoring the Message-ID field, unless BOTH emails have a defined and different Message-ID value, then they are false.

Note that Mail creates Date and Mime-Type fields if they don’t exist. The Date field is derived from the current time, so this needs to be allowed for in comparisons. (Mime-type does not depend on dynamic data, so cannot affect equality)

So, in practice the == operator works like this:

m1 = Mail.new("Subject: Hello\r\n\r\nHello")
m2 = Mail.new("Subject: Hello\r\n\r\nHello")
m1 == m2 #=> true

m1 = Mail.new("Subject: Hello\r\n\r\nHello")
m2 = Mail.new("Message-ID: <1234@test>\r\nSubject: Hello\r\n\r\nHello")
m1 == m2 #=> true

m1 = Mail.new("Message-ID: <1234@test>\r\nSubject: Hello\r\n\r\nHello")
m2 = Mail.new("Subject: Hello\r\n\r\nHello")
m1 == m2 #=> true

m1 = Mail.new("Message-ID: <1234@test>\r\nSubject: Hello\r\n\r\nHello")
m2 = Mail.new("Message-ID: <1234@test>\r\nSubject: Hello\r\n\r\nHello")
m1 == m2 #=> true

m1 = Mail.new("Message-ID: <1234@test>\r\nSubject: Hello\r\n\r\nHello")
m2 = Mail.new("Message-ID: <DIFFERENT@test>\r\nSubject: Hello\r\n\r\nHello")
m1 == m2 #=> false

# File lib/mail/message.rb, line 1341
def [](name)
  header[Utilities.underscoreize(name)]
end

Allows you to read an arbitrary header

Example:

mail['foo'] = '1234'
mail['foo'].to_s #=> '1234'

# File lib/mail/message.rb, line 1323
def []=(name, value)
  if name.to_s == 'body'
    self.body = value
  elsif /content[-_]type/i.match?(name.to_s)
    header[name] = value
  elsif name.to_s == 'charset'
    self.charset = value
  else
    header[name] = value
  end
end

Allows you to add an arbitrary header

Example:

mail['foo'] = '1234'
mail['foo'].to_s #=> '1234'

# File lib/mail/message.rb, line 1479
def add_charset
  if !body.empty?
    # Only give a warning if this isn't an attachment, has non US-ASCII and the user
    # has not specified an encoding explicitly.
    if @defaulted_charset && !body.raw_source.ascii_only? && !self.attachment?
      warning = "Non US-ASCII detected and no charset defined.\nDefaulting to UTF-8, set your own if this is incorrect.\n"
      warn(warning)
    end
    if @charset
      header[:content_type].parameters['charset'] = @charset
    end
  end
end

Adds a content type and charset if the body is US-ASCII

Otherwise raises a warning

# File lib/mail/message.rb, line 1494
def add_content_transfer_encoding
  header[:content_transfer_encoding] ||= body.default_encoding
end

Adds a content transfer encoding

# File lib/mail/message.rb, line 1472
def add_content_type
  header[:content_type] = 'text/plain'
end

Adds a content type and charset if the body is US-ASCII

Otherwise raises a warning

# File lib/mail/message.rb, line 1455
def add_date(date_val = '')
  header['date'] = date_val
end

Creates a new empty Date field and inserts it in the correct order into the Header. The DateField object will automatically generate DateTime.now’s date if you try and encode it or output it to_s without specifying a date yourself.

It will preserve any date you specify if you do.

# File lib/mail/message.rb, line 1764
def add_file(values)
  convert_to_multipart unless self.multipart? || Utilities.blank?(self.body.decoded)
  add_multipart_mixed_header
  if values.is_a?(String)
    basename = File.basename(values)
    filedata = File.open(values, 'rb') { |f| f.read }
  else
    basename = values[:filename]
    filedata = values
  end
  self.attachments[basename] = filedata
end

Adds a file to the message. You have two options with this method, you can just pass in the absolute path to the file you want and Mail will read the file, get the filename from the path you pass in and guess the MIME media type, or you can pass in the filename as a string, and pass in the file content as a blob.

Example:

m = Mail.new
m.add_file('/path/to/filename.png')

m = Mail.new
m.add_file(:filename => 'filename.png', :content => File.read('/path/to/file.jpg'))

Note also that if you add a file to an existing message, Mail will convert that message to a MIME multipart email, moving whatever plain text body you had into its own text plain part.

Example:

m = Mail.new do
  body 'this is some text'
end
m.multipart? #=> false
m.add_file('/path/to/filename.png')
m.multipart? #=> true
m.parts.first.content_type.content_type #=> 'text/plain'
m.parts.last.content_type.content_type #=> 'image/png'

See also attachments

# File lib/mail/message.rb, line 1445
def add_message_id(msg_id_val = '')
  header['message-id'] = msg_id_val
end

Creates a new empty Message-ID field and inserts it in the correct order into the Header. The MessageIdField object will automatically generate a unique message ID if you try and encode it or output it to_s without specifying a message id.

It will preserve the message ID you specify if you do.

# File lib/mail/message.rb, line 1465
def add_mime_version(ver_val = '')
  header['mime-version'] = ver_val
end

Creates a new empty Mime Version field and inserts it in the correct order into the Header. The MimeVersion object will automatically generate set itself to ‘1.0’ if you try and encode it or output it to_s without specifying a version yourself.

It will preserve any date you specify if you do.

# File lib/mail/message.rb, line 1708
def add_part(part)
  if !body.multipart? && !Utilities.blank?(self.body.decoded)
    @text_part = Mail::Part.new('Content-Type: text/plain;')
    @text_part.body = body.decoded
    self.body << @text_part
    add_multipart_alternate_header
  end
  add_boundary
  self.body << part
end

Adds a part to the parts list or creates the part list

# File lib/mail/message.rb, line 1925
def attachment
  @attachment
end

Returns the attachment data if there is any

# File lib/mail/message.rb, line 1920
def attachment?
  !!find_attachment
end

Returns true if this part is an attachment, false otherwise.

# File lib/mail/message.rb, line 1633
def attachments
  parts.attachments
end

Returns an AttachmentsList object, which holds all of the attachments in the receiver object (either the entire email or a part within) and all of its descendants.

It also allows you to add attachments to the mail object directly, like so:

mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg')

If you do this, then Mail will take the file name and work out the MIME media type set the Content-Type, Content-Disposition, Content-Transfer-Encoding and base64 encode the contents of the attachment all for you.

You can also specify overrides if you want by passing a hash instead of a string:

mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
                                    :content => File.read('/path/to/filename.jpg')}

If you want to use a different encoding than Base64, you can pass an encoding in, but then it is up to you to pass in the content pre-encoded, and don’t expect Mail to know how to decode this data:

file_content = SpecialEncode(File.read('/path/to/filename.jpg'))
mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
                                    :encoding => 'SpecialEncoding',
                                    :content => file_content }

You can also search for specific attachments:

# By Filename
mail.attachments['filename.jpg']   #=> Mail::Part object or nil

# or by index
mail.attachments[0]                #=> Mail::Part (first attachment)

# File lib/mail/message.rb, line 507
def bcc( val = nil )
  default :bcc, val
end

Returns the Bcc value of the mail object as an array of strings of address specs.

Example:

mail.bcc = 'Mikel <mikel@test.lindsaar.net>'
mail.bcc #=> ['mikel@test.lindsaar.net']
mail.bcc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.bcc 'Mikel <mikel@test.lindsaar.net>'
mail.bcc #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.bcc 'Mikel <mikel@test.lindsaar.net>'
mail.bcc << 'ada@test.lindsaar.net'
mail.bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 519
def bcc=( val )
  header[:bcc] = val
end

Sets the Bcc value of the mail object, pass in a string of the field

Example:

mail.bcc = 'Mikel <mikel@test.lindsaar.net>'
mail.bcc #=> ['mikel@test.lindsaar.net']
mail.bcc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1313
def bcc_addrs
  bcc ? [bcc].flatten : []
end

Returns an array of addresses (the encoded value) in the Bcc field, if no Bcc field, returns an empty array

# File lib/mail/message.rb, line 1258
def body(value = nil)
  if value
    self.body = value
  else
    process_body_raw if @body_raw
    @body
  end
end

Returns the body of the message object. Or, if passed a parameter sets the value.

Example:

mail = Mail::Message.new('To: mikel\r\n\r\nThis is the body')
mail.body #=> #<Mail::Body:0x13919c @raw_source="This is the bo...

mail.body 'This is another body'
mail.body #=> #<Mail::Body:0x13919c @raw_source="This is anothe...

# File lib/mail/message.rb, line 1244
def body=(value)
  body_lazy(value)
end

Sets the body object of the message object.

Example:

mail.body = 'This is the body'
mail.body #=> #<Mail::Body:0x13919c @raw_source="This is the bo...

You can also reset the body of an Message object by setting body to nil

Example:

mail.body = 'this is the body'
mail.body.encoded #=> 'this is the body'
mail.body = nil
mail.body.encoded #=> ''

If you try and set the body of an email that is a multipart email, then instead of deleting all the parts of your email, mail will add a text/plain part to your email:

mail.add_file 'somefilename.png'
mail.parts.length #=> 1
mail.body = "This is a body"
mail.parts.length #=> 2
mail.parts.last.content_type.content_type #=> 'This is a body'

# File lib/mail/message.rb, line 1590
def boundary
  content_type_parameters ? content_type_parameters['boundary'] : nil
end

Returns the current boundary for this message part

# File lib/mail/message.rb, line 548
def cc( val = nil )
  default :cc, val
end

Returns the Cc value of the mail object as an array of strings of address specs.

Example:

mail.cc = 'Mikel <mikel@test.lindsaar.net>'
mail.cc #=> ['mikel@test.lindsaar.net']
mail.cc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.cc 'Mikel <mikel@test.lindsaar.net>'
mail.cc #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.cc 'Mikel <mikel@test.lindsaar.net>'
mail.cc << 'ada@test.lindsaar.net'
mail.cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 560
def cc=( val )
  header[:cc] = val
end

Sets the Cc value of the mail object, pass in a string of the field

Example:

mail.cc = 'Mikel <mikel@test.lindsaar.net>'
mail.cc #=> ['mikel@test.lindsaar.net']
mail.cc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1307
def cc_addrs
  cc ? [cc].flatten : []
end

Returns an array of addresses (the encoded value) in the Cc field, if no Cc field, returns an empty array

# File lib/mail/message.rb, line 1504
def charset
  if @header
    has_content_type? && !multipart? ? content_type_parameters['charset'] : @charset
  else
    @charset
  end
end

Returns the character set defined in the content type field

# File lib/mail/message.rb, line 1513
def charset=(value)
  @defaulted_charset = false
  @charset = value
  @header.charset = value
end

Sets the charset to the supplied value.

# File lib/mail/message.rb, line 1530
def content_type_parameters
  has_content_type? ? header[:content_type].parameters : nil rescue nil
end

Returns the content type parameters

# File lib/mail/message.rb, line 1211
def default( sym, val = nil )
  if val
    header[sym] = val
  elsif field = header[sym]
    field.default
  end
end

Returns the default value of the field requested as a symbol.

Each header field has a :default method which returns the most common use case for that field, for example, the date field types will return a DateTime object when sent :default, the subject, or unstructured fields will return a decoded string of their value, the address field types will return a single addr_spec or an array of addr_specs if there is more than one.

# File lib/mail/message.rb, line 250
def deliver
  inform_interceptors
  if delivery_handler
    delivery_handler.deliver_mail(self) { do_delivery }
  else
    do_delivery
  end
  inform_observers
  self
end

Delivers a mail object.

Examples:

mail = Mail.read('file.eml')
mail.deliver

# File lib/mail/message.rb, line 267
def deliver!
  inform_interceptors
  response = delivery_method.deliver!(self)
  inform_observers
  delivery_method.settings[:return_response] ? response : self
end

This method bypasses checking perform_deliveries and raise_delivery_errors, so use with caution.

It still however fires off the interceptors and calls the observers callbacks if they are defined.

Returns self

# File lib/mail/message.rb, line 1550
def delivery_status_part
  unless defined? @delivery_status_part
    @delivery_status_part =
      if delivery_status_report?
        parts.detect(&:delivery_status_report_part?)
      end
  end

  @delivery_status_part
end

returns the part in a multipart/report email that has the content-type delivery-status

# File lib/mail/message.rb, line 1545
def delivery_status_report?
  multipart_report? && /^delivery-status$/i.match?(content_type_parameters['report-type'])
end

Returns true if the message is a multipart/report; report-type=delivery-status;

# File lib/mail/message.rb, line 1289
def destinations
  [to_addrs, cc_addrs, bcc_addrs].compact.flatten
end

Returns the list of addresses this message should be sent to by collecting the addresses off the to, cc and bcc fields.

Example:

mail.to = 'mikel@test.lindsaar.net'
mail.cc = 'sam@test.lindsaar.net'
mail.bcc = 'bob@test.lindsaar.net'
mail.destinations.length #=> 3
mail.destinations.first #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 1810
def encoded
  ready_to_send!
  buffer = header.encoded
  buffer << "\r\n"
  buffer << body.encoded(content_transfer_encoding)
  buffer
end

Outputs an encoded string representation of the mail message including all headers, attachments, etc. This is an encoded email in US-ASCII, so it is able to be directly sent to an email server.

# File lib/mail/message.rb, line 478
def errors
  header.errors
end

Returns a list of parser errors on the header, each field that had an error will be reparsed as an unstructured field to preserve the data inside, but will not be used for further processing.

It returns a nested array of [field_name, value, original_error_message] per error found.

Example:

message = Mail.new("Content-Transfer-Encoding: weirdo\r\n")
message.errors.size #=> 1
message.errors.first[0] #=> "Content-Transfer-Encoding"
message.errors.first[1] #=> "weirdo"
message.errors.first[2] #=> <The original error message exception>

This is a good first defence on detecting spam by the way. Some spammers send invalid emails to try and get email parsers to give up parsing them.

# File lib/mail/message.rb, line 1930
def filename
  find_attachment
end

Returns the filename of the attachment

# File lib/mail/message.rb, line 665
def from( val = nil )
  default :from, val
end

Returns the From value of the mail object as an array of strings of address specs.

Example:

mail.from = 'Mikel <mikel@test.lindsaar.net>'
mail.from #=> ['mikel@test.lindsaar.net']
mail.from = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.from 'Mikel <mikel@test.lindsaar.net>'
mail.from #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.from 'Mikel <mikel@test.lindsaar.net>'
mail.from << 'ada@test.lindsaar.net'
mail.from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 677
def from=( val )
  header[:from] = val
end

Sets the From value of the mail object, pass in a string of the field

Example:

mail.from = 'Mikel <mikel@test.lindsaar.net>'
mail.from #=> ['mikel@test.lindsaar.net']
mail.from = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1295
def from_addrs
  from ? [from].flatten : []
end

Returns an array of addresses (the encoded value) in the From field, if no From field, returns an empty array

# File lib/mail/message.rb, line 1415
def has_date?
  header.has_date?
end

Returns true if the message has a Date field, the field may or may not have a value, but the field exists or not.

# File lib/mail/message.rb, line 1409
def has_message_id?
  header.has_message_id?
end

Returns true if the message has a message ID field, the field may or may not have a value, but the field exists or not.

# File lib/mail/message.rb, line 1421
def has_mime_version?
  header.has_mime_version?
end

Returns true if the message has a MIME-Version field, the field may or may not have a value, but the field exists or not.

# File lib/mail/message.rb, line 450
def header(value = nil)
  value ? self.header = value : @header
end

Returns the header object of the message object. Or, if passed a parameter sets the value.

Example:

mail = Mail::Message.new('To: mikel\r\nFrom: you')
mail.header #=> #<Mail::Header:0x13ce14 @raw_source="To: mikel\r\nFr...

mail.header #=> nil
mail.header 'To: mikel\r\nFrom: you'
mail.header #=> #<Mail::Header:0x13ce14 @raw_source="To: mikel\r\nFr...

# File lib/mail/message.rb, line 435
def header=(value)
  @header = Mail::Header.new(value, charset)
end

Sets the header of the message object.

Example:

mail.header = 'To: mikel@test.lindsaar.net\r\nFrom: Bob@bob.com'
mail.header #=> <#Mail::Header

# File lib/mail/message.rb, line 1403
def header_fields
  header.fields
end

Returns an FieldList of all the fields in the header in the order that they appear in the header

# File lib/mail/message.rb, line 455
def headers(hash = {})
  hash.each_pair do |k,v|
    header[k] = v
  end
end

Provides a way to set custom headers, by passing in a hash

# File lib/mail/message.rb, line 1642
def html_part(&block)
  if block_given?
    self.html_part = Mail::Part.new(:content_type => 'text/html', &block)
  else
    @html_part || find_first_mime_type('text/html')
  end
end

Accessor for html_part

# File lib/mail/message.rb, line 1662
def html_part=(msg)
  # Assign the html part and set multipart/alternative if there's a text part.
  if msg
    msg = Mail::Part.new(:body => msg) unless msg.kind_of?(Mail::Message)

    @html_part = msg
    @html_part.content_type = 'text/html' unless @html_part.has_content_type?
    add_multipart_alternate_header if text_part
    add_part @html_part

  # If nil, delete the html part and back out of multipart/alternative.
  elsif @html_part
    parts.delete_if { |p| p.object_id == @html_part.object_id }
    @html_part = nil
    if text_part
      self.content_type = nil
      body.boundary = nil
    end
  end
end

Helper to add a html part to a multipart/alternative email. If this and text_part are both defined in a message, then it will be a multipart/alternative message and set itself that way.

# File lib/mail/message.rb, line 1967
def is_marked_for_delete?
  return @mark_for_delete
end

Returns whether message will be marked for deletion. If so, the message will be deleted at session close (i.e. after find exits), but only if also using the find_and_delete method, or by calling find with :delete_after_find set to true.

Side-note: Just to be clear, this method will return true even if the message hasn’t yet been marked for delete on the mail server. However, if this method returns true, it *will be* marked on the server after each block yields back to find or find_and_delete.

# File lib/mail/message.rb, line 1520
def main_type
  has_content_type? ? header[:content_type].main_type : nil rescue nil
end

Returns the main content type

# File lib/mail/message.rb, line 1954
def mark_for_delete=(value = true)
  @mark_for_delete = value
end

Sets whether this message should be deleted at session close (i.e. after find). Message will only be deleted if messages are retrieved using the find_and_delete method, or by calling find with :delete_after_find set to true.

# File lib/mail/message.rb, line 710
def message_id( val = nil )
  default :message_id, val
end

Returns the Message-ID of the mail object. Note, per RFC 2822 the Message ID consists of what is INSIDE the < > usually seen in the mail header, so this method will return only what is inside.

Example:

mail.message_id = '<1234@message.id>'
mail.message_id #=> '1234@message.id'

Also allows you to set the Message-ID by passing a string as a parameter

mail.message_id '<1234@message.id>'
mail.message_id #=> '1234@message.id'

# File lib/mail/message.rb, line 719
def message_id=( val )
  header[:message_id] = val
end

Sets the Message-ID. Note, per RFC 2822 the Message ID consists of what is INSIDE the < > usually seen in the mail header, so this method will return only what is inside.

mail.message_id = '<1234@message.id>'
mail.message_id #=> '1234@message.id'

# File lib/mail/message.rb, line 1499
def mime_type
  has_content_type? ? header[:content_type].string : nil rescue nil
end

Returns the MIME media type of part we are on, this is taken from the content-type header

# File lib/mail/message.rb, line 736
def mime_version( val = nil )
  default :mime_version, val
end

Returns the MIME version of the email as a string

Example:

mail.mime_version = '1.0'
mail.mime_version #=> '1.0'

Also allows you to set the MIME version by passing a string as a parameter.

Example:

mail.mime_version '1.0'
mail.mime_version #=> '1.0'

# File lib/mail/message.rb, line 746
def mime_version=( val )
  header[:mime_version] = val
end

Sets the MIME version of the email by accepting a string

Example:

mail.mime_version = '1.0'
mail.mime_version #=> '1.0'

# File lib/mail/message.rb, line 1535
def multipart?
  has_content_type? ? /^multipart$/i.match?(main_type) : false
end

Returns true if the message is multipart

# File lib/mail/message.rb, line 1540
def multipart_report?
  multipart? && /^report$/i.match?(sub_type)
end

Returns true if the message is a multipart/report

# File lib/mail/message.rb, line 1729
def part(params = {})
  new_part = Part.new(params)
  yield new_part if block_given?
  add_part(new_part)
end

Allows you to add a part in block form to an existing mail message object

Example:

mail = Mail.new do
  part :content_type => "multipart/alternative", :content_disposition => "inline" do |p|
    p.part :content_type => "text/plain", :body => "test text\nline #2"
    p.part :content_type => "text/html", :body => "<b>test</b> HTML<br/>\nline #2"
  end
end

# File lib/mail/message.rb, line 1595
def parts
  body.parts
end

Returns a parts list object of all the parts in the message

# File lib/mail/message.rb, line 417
def raw_envelope
  @raw_envelope
end

The raw_envelope is the From mikel@test.lindsaar.net Mon May 2 16:07:05 2009 type field that you can see at the top of any email that has come from a mailbox

# File lib/mail/message.rb, line 404
def raw_source
  @raw_source
end

Provides access to the raw source of the message as it was when it was instantiated. This is set at initialization and so is untouched by the parsers or decoder / encoders

Example:

mail = Mail.new('This is an invalid email message')
mail.raw_source #=> "This is an invalid email message"

# File lib/mail/message.rb, line 1798
def ready_to_send!
  identify_and_set_transfer_encoding
  parts.each do |part|
    part.transport_encoding = transport_encoding
    part.ready_to_send!
  end
  add_required_fields
end

Encodes the message, calls encode on all its parts, gets an email message ready to send

# File lib/mail/message.rb, line 795
def reply_to( val = nil )
  default :reply_to, val
end

Returns the Reply-To value of the mail object as an array of strings of address specs.

Example:

mail.reply_to = 'Mikel <mikel@test.lindsaar.net>'
mail.reply_to #=> ['mikel@test.lindsaar.net']
mail.reply_to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.reply_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.reply_to 'Mikel <mikel@test.lindsaar.net>'
mail.reply_to #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.reply_to 'Mikel <mikel@test.lindsaar.net>'
mail.reply_to << 'ada@test.lindsaar.net'
mail.reply_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 807
def reply_to=( val )
  header[:reply_to] = val
end

Sets the Reply-To value of the mail object, pass in a string of the field

Example:

mail.reply_to = 'Mikel <mikel@test.lindsaar.net>'
mail.reply_to #=> ['mikel@test.lindsaar.net']
mail.reply_to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.reply_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 836
def resent_bcc( val = nil )
  default :resent_bcc, val
end

Returns the Resent-Bcc value of the mail object as an array of strings of address specs.

Example:

mail.resent_bcc = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_bcc #=> ['mikel@test.lindsaar.net']
mail.resent_bcc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.resent_bcc 'Mikel <mikel@test.lindsaar.net>'
mail.resent_bcc #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.resent_bcc 'Mikel <mikel@test.lindsaar.net>'
mail.resent_bcc << 'ada@test.lindsaar.net'
mail.resent_bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 848
def resent_bcc=( val )
  header[:resent_bcc] = val
end

Sets the Resent-Bcc value of the mail object, pass in a string of the field

Example:

mail.resent_bcc = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_bcc #=> ['mikel@test.lindsaar.net']
mail.resent_bcc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 877
def resent_cc( val = nil )
  default :resent_cc, val
end

Returns the Resent-Cc value of the mail object as an array of strings of address specs.

Example:

mail.resent_cc = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_cc #=> ['mikel@test.lindsaar.net']
mail.resent_cc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.resent_cc 'Mikel <mikel@test.lindsaar.net>'
mail.resent_cc #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.resent_cc 'Mikel <mikel@test.lindsaar.net>'
mail.resent_cc << 'ada@test.lindsaar.net'
mail.resent_cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 889
def resent_cc=( val )
  header[:resent_cc] = val
end

Sets the Resent-Cc value of the mail object, pass in a string of the field

Example:

mail.resent_cc = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_cc #=> ['mikel@test.lindsaar.net']
mail.resent_cc = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 926
def resent_from( val = nil )
  default :resent_from, val
end

Returns the Resent-From value of the mail object as an array of strings of address specs.

Example:

mail.resent_from = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_from #=> ['mikel@test.lindsaar.net']
mail.resent_from = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.resent_from ['Mikel <mikel@test.lindsaar.net>']
mail.resent_from #=> 'mikel@test.lindsaar.net'

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.resent_from 'Mikel <mikel@test.lindsaar.net>'
mail.resent_from << 'ada@test.lindsaar.net'
mail.resent_from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 938
def resent_from=( val )
  header[:resent_from] = val
end

Sets the Resent-From value of the mail object, pass in a string of the field

Example:

mail.resent_from = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_from #=> ['mikel@test.lindsaar.net']
mail.resent_from = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 965
def resent_sender( val = nil )
  default :resent_sender, val
end

Returns the Resent-Sender value of the mail object, as a single string of an address spec. A sender per RFC 2822 must be a single address, so you can not append to this address.

Example:

mail.resent_sender = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_sender #=> 'mikel@test.lindsaar.net'

Also allows you to set the value by passing a value as a parameter

Example:

mail.resent_sender 'Mikel <mikel@test.lindsaar.net>'
mail.resent_sender #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 975
def resent_sender=( val )
  header[:resent_sender] = val
end

Sets the Resent-Sender value of the mail object, pass in a string of the field

Example:

mail.resent_sender = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_sender #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 1004
def resent_to( val = nil )
  default :resent_to, val
end

Returns the Resent-To value of the mail object as an array of strings of address specs.

Example:

mail.resent_to = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_to #=> ['mikel@test.lindsaar.net']
mail.resent_to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.resent_to 'Mikel <mikel@test.lindsaar.net>'
mail.resent_to #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.resent_to 'Mikel <mikel@test.lindsaar.net>'
mail.resent_to << 'ada@test.lindsaar.net'
mail.resent_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1016
def resent_to=( val )
  header[:resent_to] = val
end

Sets the Resent-To value of the mail object, pass in a string of the field

Example:

mail.resent_to = 'Mikel <mikel@test.lindsaar.net>'
mail.resent_to #=> ['mikel@test.lindsaar.net']
mail.resent_to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.resent_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1021
def return_path( val = nil )
  default :return_path, val
end

Returns the return path of the mail object, or sets it if you pass a string

# File lib/mail/message.rb, line 1026
def return_path=( val )
  header[:return_path] = val
end

Sets the return path of the object

# File lib/mail/message.rb, line 1044
def sender( val = nil )
  default :sender, val
end

Returns the Sender value of the mail object, as a single string of an address spec. A sender per RFC 2822 must be a single address.

Example:

mail.sender = 'Mikel <mikel@test.lindsaar.net>'
mail.sender #=> 'mikel@test.lindsaar.net'

Also allows you to set the value by passing a value as a parameter

Example:

mail.sender 'Mikel <mikel@test.lindsaar.net>'
mail.sender #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 1054
def sender=( val )
  header[:sender] = val
end

Sets the Sender value of the mail object, pass in a string of the field

Example:

mail.sender = 'Mikel <mikel@test.lindsaar.net>'
mail.sender #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 409
def set_envelope(val)
  @raw_envelope = val
  @envelope = Mail::Envelope.parse(val) rescue nil
end

Sets the envelope from for the email

# File lib/mail/message.rb, line 1946
def skip_deletion
  @mark_for_delete = false
end

Skips the deletion of this message. All other messages flagged for delete still will be deleted at session close (i.e. when find exits). Only has an effect if you’re using find_and_delete or find with :delete_after_find set to true.

# File lib/mail/message.rb, line 1074
def smtp_envelope_from( val = nil )
  if val
    self.smtp_envelope_from = val
  else
    @smtp_envelope_from || return_path || sender || from_addrs.first
  end
end

Returns the SMTP Envelope From value of the mail object, as a single string of an address spec.

Defaults to Return-Path, Sender, or the first From address.

Example:

mail.smtp_envelope_from = 'Mikel <mikel@test.lindsaar.net>'
mail.smtp_envelope_from #=> 'mikel@test.lindsaar.net'

Also allows you to set the value by passing a value as a parameter

Example:

mail.smtp_envelope_from 'Mikel <mikel@test.lindsaar.net>'
mail.smtp_envelope_from #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 1088
def smtp_envelope_from=( val )
  @smtp_envelope_from = val
end

Sets the From address on the SMTP Envelope.

Example:

mail.smtp_envelope_from = 'Mikel <mikel@test.lindsaar.net>'
mail.smtp_envelope_from #=> 'mikel@test.lindsaar.net'

# File lib/mail/message.rb, line 1107
def smtp_envelope_to( val = nil )
  if val
    self.smtp_envelope_to = val
  else
    @smtp_envelope_to || destinations
  end
end

Returns the SMTP Envelope To value of the mail object.

Defaults to destinations: To, Cc, and Bcc addresses.

Example:

mail.smtp_envelope_to = 'Mikel <mikel@test.lindsaar.net>'
mail.smtp_envelope_to #=> 'mikel@test.lindsaar.net'

Also allows you to set the value by passing a value as a parameter

Example:

mail.smtp_envelope_to ['Mikel <mikel@test.lindsaar.net>', 'Lindsaar <lindsaar@test.lindsaar.net>']
mail.smtp_envelope_to #=> ['mikel@test.lindsaar.net', 'lindsaar@test.lindsaar.net']

# File lib/mail/message.rb, line 1124
def smtp_envelope_to=( val )
  @smtp_envelope_to =
    case val
    when Array, NilClass
      val
    else
      [val]
    end
end

Sets the To addresses on the SMTP Envelope.

Example:

mail.smtp_envelope_to = 'Mikel <mikel@test.lindsaar.net>'
mail.smtp_envelope_to #=> 'mikel@test.lindsaar.net'

mail.smtp_envelope_to = ['Mikel <mikel@test.lindsaar.net>', 'Lindsaar <lindsaar@test.lindsaar.net>']
mail.smtp_envelope_to #=> ['mikel@test.lindsaar.net', 'lindsaar@test.lindsaar.net']

# File lib/mail/message.rb, line 1525
def sub_type
  has_content_type? ? header[:content_type].sub_type : nil rescue nil
end

Returns the sub content type

# File lib/mail/message.rb, line 1149
def subject( val = nil )
  default :subject, val
end

Returns the decoded value of the subject field, as a single string.

Example:

mail.subject = "G'Day mate"
mail.subject #=> "G'Day mate"
mail.subject = '=?UTF-8?Q?This_is_=E3=81=82_string?='
mail.subject #=> "This is あ string"

Also allows you to set the value by passing a value as a parameter

Example:

mail.subject "G'Day mate"
mail.subject #=> "G'Day mate"

# File lib/mail/message.rb, line 1159
def subject=( val )
  header[:subject] = val
end

Sets the Subject value of the mail object, pass in a string of the field

Example:

mail.subject = '=?UTF-8?Q?This_is_=E3=81=82_string?='
mail.subject #=> "This is あ string"

# File lib/mail/message.rb, line 1651
def text_part(&block)
  if block_given?
    self.text_part = Mail::Part.new(:content_type => 'text/plain', &block)
  else
    @text_part || find_first_mime_type('text/plain')
  end
end

Accessor for text_part

# File lib/mail/message.rb, line 1686
def text_part=(msg)
  # Assign the text part and set multipart/alternative if there's an html part.
  if msg
    msg = Mail::Part.new(:body => msg) unless msg.kind_of?(Mail::Message)

    @text_part = msg
    @text_part.content_type = 'text/plain' unless @text_part.has_content_type?
    add_multipart_alternate_header if html_part
    add_part @text_part

  # If nil, delete the text part and back out of multipart/alternative.
  elsif @text_part
    parts.delete_if { |p| p.object_id == @text_part.object_id }
    @text_part = nil
    if html_part
      self.content_type = nil
      body.boundary = nil
    end
  end
end

Helper to add a text part to a multipart/alternative email. If this and html_part are both defined in a message, then it will be a multipart/alternative message and set itself that way.

# File lib/mail/message.rb, line 1188
def to( val = nil )
  default :to, val
end

Returns the To value of the mail object as an array of strings of address specs.

Example:

mail.to = 'Mikel <mikel@test.lindsaar.net>'
mail.to #=> ['mikel@test.lindsaar.net']
mail.to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

Also allows you to set the value by passing a value as a parameter

Example:

mail.to 'Mikel <mikel@test.lindsaar.net>'
mail.to #=> ['mikel@test.lindsaar.net']

Additionally, you can append new addresses to the returned Array like object.

Example:

mail.to 'Mikel <mikel@test.lindsaar.net>'
mail.to << 'ada@test.lindsaar.net'
mail.to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1200
def to=( val )
  header[:to] = val
end

Sets the To value of the mail object, pass in a string of the field

Example:

mail.to = 'Mikel <mikel@test.lindsaar.net>'
mail.to #=> ['mikel@test.lindsaar.net']
mail.to = 'Mikel <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
mail.to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']

# File lib/mail/message.rb, line 1301
def to_addrs
  to ? [to].flatten : []
end

Returns an array of addresses (the encoded value) in the To field, if no To field, returns an empty array