Class: Mail::Message

Inherits:
Object show all
Includes:
Patterns, Utilities
Defined in:
lib/mail/message.rb

Overview

The Message class provides a single point of access to all things to do with an email message.

You create a new email message by calling the Mail::Message.new method, or just Mail.new

A Message object by default has the following objects inside it:

  • A Header object which contains all information and settings of the header of the email

  • Body object which contains all parts of the email that are not part of the header, this includes any attachments, body text, MIME parts etc.

Per RFC2822

2.1. General Description

 At the most basic level, a message is a series of characters.  A
 message that is conformant with this standard is comprised of
 characters with values in the range 1 through 127 and interpreted as
 US-ASCII characters [ASCII].  For brevity, this document sometimes
 refers to this range of characters as simply "US-ASCII characters".

 Note: This standard specifies that messages are made up of characters
 in the US-ASCII range of 1 through 127.  There are other documents,
 specifically the MIME document series [RFC2045, RFC2046, RFC2047,
 RFC2048, RFC2049], that extend this standard to allow for values
 outside of that range.  Discussion of those mechanisms is not within
 the scope of this standard.

 Messages are divided into lines of characters.  A line is a series of
 characters that is delimited with the two characters carriage-return
 and line-feed; that is, the carriage return (CR) character (ASCII
 value 13) followed immediately by the line feed (LF) character (ASCII
 value 10).  (The carriage-return/line-feed pair is usually written in
 this document as "CRLF".)

 A message consists of header fields (collectively called "the header
 of the message") followed, optionally, by a body.  The header is a
 sequence of lines of characters with special syntax as defined in
 this standard. The body is simply a sequence of characters that
 follows the header and is separated from the header by an empty line
 (i.e., a line with nothing preceding the CRLF).

Direct Known Subclasses

Part

Constant Summary

Constant Summary

Constants included from Patterns

Patterns::ATOM_UNSAFE, Patterns::CONTROL_CHAR, Patterns::CRLF, Patterns::FIELD_BODY, Patterns::FIELD_LINE, Patterns::FIELD_NAME, Patterns::FIELD_SPLIT, Patterns::FWS, Patterns::HEADER_LINE, Patterns::PHRASE_UNSAFE, Patterns::QP_SAFE, Patterns::QP_UNSAFE, Patterns::TEXT, Patterns::TOKEN_UNSAFE, Patterns::WSP

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Utilities

#atom_safe?, #bracket, #capitalize_field, #constantize, #dasherize, #dquote, #escape_paren, #map_lines, #map_with_index, #match_to_s, #paren, #quote_atom, #quote_phrase, #quote_token, #token_safe?, #unbracket, #underscoreize, #unparen, #unquote, #uri_escape, #uri_parser, #uri_unescape

Constructor Details

- (Message) initialize(*args, &block)

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
     from 'mikel@test.lindsaar.net'
       to 'you@test.lindsaar.net'
  subject 'This is a test email'
     body File.read('body.txt')
end

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

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@...


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/mail/message.rb', line 100

def initialize(*args, &block)
  @body = nil
  @body_raw = nil
  @separate_parts = false
  @text_part = nil
  @html_part = nil
  @errors = nil
  @header = nil
  @charset = 'UTF-8'
  @defaulted_charset = true

  @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

  if block_given?
    instance_eval(&block)
  end

  self
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(name, *args, &block)

Method Missing in this implementation allows you to set any of the standard fields directly as you would the “to”, “subject” etc.

Those fields used most often (to, subject et al) are given their own method for ease of documentation and also to avoid the hook call to method missing.

This will only catch the known fields listed in:

Mail::Field::KNOWN_FIELDS

as per RFC 2822, any ruby string or method name could pretty much be a field name, so we don't want to just catch ANYTHING sent to a message object and interpret it as a header.

This method provides all three types of header call to set, read and explicitly set with the = operator

Examples:

mail.comments = 'These are some comments'
mail.comments #=> 'These are some comments'

mail.comments 'These are other comments'
mail.comments #=> 'These are other comments'

mail.date = 'Tue, 1 Jul 2003 10:52:37 +0200'
mail.date.to_s #=> 'Tue, 1 Jul 2003 10:52:37 +0200'

mail.date 'Tue, 1 Jul 2003 10:52:37 +0200'
mail.date.to_s #=> 'Tue, 1 Jul 2003 10:52:37 +0200'

mail.resent_msg_id = '<1234@resent_msg_id.lindsaar.net>'
mail.resent_msg_id #=> '<1234@resent_msg_id.lindsaar.net>'

mail.resent_msg_id '<4567@resent_msg_id.lindsaar.net>'
mail.resent_msg_id #=> '<4567@resent_msg_id.lindsaar.net>'


1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
 
# File 'lib/mail/message.rb', line 1277

def method_missing(name, *args, &block)
  #:nodoc:
  # Only take the structured fields, as we could take _anything_ really
  # as it could become an optional field... "but therin lies the dark side"
  field_name = underscoreize(name).chomp("=")
  if Mail::Field::KNOWN_FIELDS.include?(field_name)
    if args.empty?
      header[field_name]
    else
      header[field_name] = args.first
    end
  else
    super # otherwise pass it on
  end
  #:startdoc:
end

Instance Attribute Details

- (Object) delivery_handler

If you assign a delivery handler, mail will call :deliver_mail on the object you assign to delivery_handler, it will pass itself as the single argument.

If you define a delivery_handler, then you are responsible for the following actions in the delivery cycle:

  • Appending the mail object to Mail.deliveries as you see fit.

  • Checking the mail.perform_deliveries flag to decide if you should actually call :deliver! the mail object or not.

  • Checking the mail.raise_delivery_errors flag to decide if you should raise delivery errors if they occur.

  • Actually calling :deliver! (with the bang) on the mail object to get it to deliver itself.

A simplest implementation of a delivery_handler would be

class MyObject

  def initialize
    @mail = Mail.new('To: mikel@test.lindsaar.net')
    @mail.delivery_handler = self
  end

  attr_accessor :mail

  def deliver_mail(mail)
    yield
  end
end

Then doing:

obj = MyObject.new
obj.mail.deliver

Would cause Mail to call obj.deliver_mail passing itself as a parameter, which then can just yield and let Mail do its own private do_delivery method.



174
175
176
 
# File 'lib/mail/message.rb', line 174

def delivery_handler
  @delivery_handler
end

- (Object) perform_deliveries

If set to false, mail will go through the motions of doing a delivery, but not actually call the delivery method or append the mail object to the Mail.deliveries collection. Useful for testing.

Mail.deliveries.size #=> 0
mail.delivery_method :smtp
mail.perform_deliveries = false
mail.deliver                        # Mail::SMTP not called here
Mail.deliveries.size #=> 0

If you want to test and query the Mail.deliveries collection to see what mail you sent, you should set perform_deliveries to true and use the :test mail delivery_method:

Mail.deliveries.size #=> 0
mail.delivery_method :test
mail.perform_deliveries = true
mail.deliver
Mail.deliveries.size #=> 1

This setting is ignored by mail (though still available as a flag) if you define a delivery_handler



198
199
200
 
# File 'lib/mail/message.rb', line 198

def perform_deliveries
  @perform_deliveries
end

- (Object) raise_delivery_errors

If set to false, mail will silently catch and ignore any exceptions raised through attempting to deliver an email.

This setting is ignored by mail (though still available as a flag) if you define a delivery_handler



205
206
207
 
# File 'lib/mail/message.rb', line 205

def raise_delivery_errors
  @raise_delivery_errors
end

Class Method Details

+ (Object) from_hash(hash) 



1785
1786
1787
 
# File 'lib/mail/message.rb', line 1785

def self.from_hash(hash)
  Mail::Message.new(hash)
end

+ (Object) from_yaml(str) 



1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
 
# File 'lib/mail/message.rb', line 1763

def self.from_yaml(str)
  hash = YAML.load(str)
  m = self.new(:headers => hash['headers'])
  hash.delete('headers')
  hash.each do |k,v|
    case
    when k == 'delivery_handler'
      begin
        m.delivery_handler = Object.const_get(v) unless v.blank?
      rescue NameError
      end
    when k == 'transport_encoding'
      m.transport_encoding(v)
    when k == 'multipart_body'
      v.map {|part| m.add_part Mail::Part.from_yaml(part) }
    when k =~ /^@/
      m.instance_variable_set(k.to_sym, v)
    end
  end
  m
end

Instance Method Details

- (Object) <=>(other)

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]


310
311
312
313
314
315
316
 
# File 'lib/mail/message.rb', line 310

def <=>(other)
  if other.nil?
    1
  else
    self.date <=> other.date
  end
end

- (Object) ==(other)

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.

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


349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/mail/message.rb', line 349

def ==(other)
  return false unless other.respond_to?(:encoded)

  if self.message_id && other.message_id
    result = (self.encoded == other.encoded)
  else
    self_message_id, other_message_id = self.message_id, other.message_id
    self.message_id, other.message_id = '<temp@test>', '<temp@test>'
    result = self.encoded == other.encoded
    self.message_id = "<#{self_message_id}>" if self_message_id
    other.message_id = "<#{other_message_id}>" if other_message_id
    result
  end
end

- (Object) [](name)

Allows you to read an arbitrary header

Example:

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


1234
1235
1236
 
# File 'lib/mail/message.rb', line 1234

def [](name)
  header[underscoreize(name)]
end

- (Object) []=(name, value)

Allows you to add an arbitrary header

Example:

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


1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
 
# File 'lib/mail/message.rb', line 1216

def []=(name, value)
  if name.to_s == 'body'
    self.body = value
  elsif name.to_s =~ /content[-_]type/i
    header[name] = value
  elsif name.to_s == 'charset'
    self.charset = value
  else
    header[name] = value
  end
end

- (Object) action 



1483
1484
1485
 
# File 'lib/mail/message.rb', line 1483

def action
  delivery_status_part and delivery_status_part.action
end

- (Object) add_charset

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

Otherwise raises a warning



1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
 
# File 'lib/mail/message.rb', line 1377

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.not_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"
      STDERR.puts(warning)
    end
    header[:content_type].parameters['charset'] = @charset
  end
end

- (Object) add_content_transfer_encoding

Adds a content transfer encoding

Otherwise raises a warning



1392
1393
1394
1395
1396
1397
1398
1399
1400
 
# File 'lib/mail/message.rb', line 1392

def add_content_transfer_encoding
  if body.only_us_ascii?
    header[:content_transfer_encoding] = '7bit'
  else
    warning = "Non US-ASCII detected and no content-transfer-encoding defined.\nDefaulting to 8bit, set your own if this is incorrect.\n"
    STDERR.puts(warning)
    header[:content_transfer_encoding] = '8bit'
  end
end

- (Object) add_content_type

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

Otherwise raises a warning



1370
1371
1372
 
# File 'lib/mail/message.rb', line 1370

def add_content_type
  header[:content_type] = 'text/plain'
end

- (Object) add_date(date_val = '')

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.



1353
1354
1355
 
# File 'lib/mail/message.rb', line 1353

def add_date(date_val = '')
  header['date'] = date_val
end

- (Object) add_file(values)

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



1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
 
# File 'lib/mail/message.rb', line 1678

def add_file(values)
  convert_to_multipart unless self.multipart? || self.body.decoded.blank?
  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[:content] || File.open(values[:filename], 'rb') { |f| f.read }
  end
  self.attachments[basename] = filedata
end

- (Object) add_message_id(msg_id_val = '')

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.



1343
1344
1345
 
# File 'lib/mail/message.rb', line 1343

def add_message_id(msg_id_val = '')
  header['message-id'] = msg_id_val
end

- (Object) add_mime_version(ver_val = '')

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.



1363
1364
1365
 
# File 'lib/mail/message.rb', line 1363

def add_mime_version(ver_val = '')
  header['mime-version'] = ver_val
end

- (Object) add_part(part)

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



1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
 
# File 'lib/mail/message.rb', line 1622

def add_part(part)
  if !body.multipart? && !self.body.decoded.blank?
    @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

- (Object) add_transfer_encoding

:nodoc:



1402
1403
1404
1405
 
# File 'lib/mail/message.rb', line 1402

def add_transfer_encoding # :nodoc:
  STDERR.puts(":add_transfer_encoding is deprecated in Mail 1.4.3.  Please use add_content_transfer_encoding\n#{caller}")
  add_content_transfer_encoding
end

- (Object) all_parts 



1838
1839
1840
 
# File 'lib/mail/message.rb', line 1838

def all_parts
  parts.map { |p| [p, p.all_parts] }.flatten
end

- (Object) attachment

Returns the attachment data if there is any



1829
1830
1831
 
# File 'lib/mail/message.rb', line 1829

def attachment
  @attachment
end

- (Boolean) attachment?

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

Returns:

  • (Boolean) 


1824
1825
1826
 
# File 'lib/mail/message.rb', line 1824

def attachment?
  !!find_attachment
end

- (Object) attachments

Returns an AttachmentsList object, which holds all of the attachments in the receiver object (either the entier 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)


1551
1552
1553
 
# File 'lib/mail/message.rb', line 1551

def attachments
  parts.attachments
end

- (Object) bcc(val = nil)

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


475
476
477
 
# File 'lib/mail/message.rb', line 475

def bcc( val = nil )
  default :bcc, val
end

- (Object) bcc=(val)

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


487
488
489
 
# File 'lib/mail/message.rb', line 487

def bcc=( val )
  header[:bcc] = val
end

- (Object) bcc_addrs

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



1206
1207
1208
 
# File 'lib/mail/message.rb', line 1206

def bcc_addrs
  bcc ? [bcc].flatten : []
end

- (Object) body(value = nil)

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...


1150
1151
1152
1153
1154
1155
1156
1157
1158
 
# File 'lib/mail/message.rb', line 1150

def body(value = nil)
  if value
    self.body = value
#        add_encoding_to_body
  else
    process_body_raw if @body_raw
    @body
  end
end

- (Object) body=(value)

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'


1136
1137
1138
 
# File 'lib/mail/message.rb', line 1136

def body=(value)
  body_lazy(value)
end

- (Object) body_encoding(value) 



1160
1161
1162
1163
1164
1165
1166
 
# File 'lib/mail/message.rb', line 1160

def body_encoding(value)
  if value.nil?
    body.encoding
  else
    body.encoding = value
  end
end

- (Object) body_encoding=(value) 



1168
1169
1170
 
# File 'lib/mail/message.rb', line 1168

def body_encoding=(value)
    body.encoding = value
end

- (Boolean) bounced?

Returns:

  • (Boolean) 


1479
1480
1481
 
# File 'lib/mail/message.rb', line 1479

def bounced?
  delivery_status_part and delivery_status_part.bounced?
end

- (Object) boundary

Returns the current boundary for this message part



1508
1509
1510
 
# File 'lib/mail/message.rb', line 1508

def boundary
  content_type_parameters ? content_type_parameters['boundary'] : nil
end

- (Object) cc(val = nil)

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


516
517
518
 
# File 'lib/mail/message.rb', line 516

def cc( val = nil )
  default :cc, val
end

- (Object) cc=(val)

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


528
529
530
 
# File 'lib/mail/message.rb', line 528

def cc=( val )
  header[:cc] = val
end

- (Object) cc_addrs

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



1200
1201
1202
 
# File 'lib/mail/message.rb', line 1200

def cc_addrs
  cc ? [cc].flatten : []
end

- (Object) charset

Returns the character set defined in the content type field



1423
1424
1425
1426
1427
1428
1429
 
# File 'lib/mail/message.rb', line 1423

def charset
  if @header
    has_content_type? ? content_type_parameters['charset'] : @charset
  else
    @charset
  end
end

- (Object) charset=(value)

Sets the charset to the supplied value.



1432
1433
1434
1435
1436
 
# File 'lib/mail/message.rb', line 1432

def charset=(value)
  @defaulted_charset = false
  @charset = value
  @header.charset = value
end

- (Object) comments(val = nil) 



532
533
534
 
# File 'lib/mail/message.rb', line 532

def comments( val = nil )
  default :comments, val
end

- (Object) comments=(val) 



536
537
538
 
# File 'lib/mail/message.rb', line 536

def comments=( val )
  header[:comments] = val
end

- (Object) content_description(val = nil) 



540
541
542
 
# File 'lib/mail/message.rb', line 540

def content_description( val = nil )
  default :content_description, val
end

- (Object) content_description=(val) 



544
545
546
 
# File 'lib/mail/message.rb', line 544

def content_description=( val )
  header[:content_description] = val
end

- (Object) content_disposition(val = nil) 



548
549
550
 
# File 'lib/mail/message.rb', line 548

def content_disposition( val = nil )
  default :content_disposition, val
end

- (Object) content_disposition=(val) 



552
553
554
 
# File 'lib/mail/message.rb', line 552

def content_disposition=( val )
  header[:content_disposition] = val
end

- (Object) content_id(val = nil) 



556
557
558
 
# File 'lib/mail/message.rb', line 556

def content_id( val = nil )
  default :content_id, val
end

- (Object) content_id=(val) 



560
561
562
 
# File 'lib/mail/message.rb', line 560

def content_id=( val )
  header[:content_id] = val
end

- (Object) content_location(val = nil) 



564
565
566
 
# File 'lib/mail/message.rb', line 564

def content_location( val = nil )
  default :content_location, val
end

- (Object) content_location=(val) 



568
569
570
 
# File 'lib/mail/message.rb', line 568

def content_location=( val )
  header[:content_location] = val
end

- (Object) content_transfer_encoding(val = nil) 



572
573
574
 
# File 'lib/mail/message.rb', line 572

def content_transfer_encoding( val = nil )
  default :content_transfer_encoding, val
end

- (Object) content_transfer_encoding=(val) 



576
577
578
 
# File 'lib/mail/message.rb', line 576

def content_transfer_encoding=( val )
  header[:content_transfer_encoding] = val
end

- (Object) content_type(val = nil) 



580
581
582
 
# File 'lib/mail/message.rb', line 580

def content_type( val = nil )
  default :content_type, val
end

- (Object) content_type=(val) 



584
585
586
 
# File 'lib/mail/message.rb', line 584

def content_type=( val )
  header[:content_type] = val
end

- (Object) content_type_parameters

Returns the content type parameters



1455
1456
1457
 
# File 'lib/mail/message.rb', line 1455

def content_type_parameters
  has_content_type? ? header[:content_type].parameters : nil rescue nil
end

- (Object) convert_to_multipart 



1691
1692
1693
1694
1695
1696
1697
1698
 
# File 'lib/mail/message.rb', line 1691

def convert_to_multipart
  text = body.decoded
  self.body = ''
  text_part = Mail::Part.new({:content_type => 'text/plain;',
                              :body => text})
  text_part.charset = charset unless @defaulted_charset
  self.body << text_part
end

- (Object) date(val = nil) 



588
589
590
 
# File 'lib/mail/message.rb', line 588

def date( val = nil )
  default :date, val
end

- (Object) date=(val) 



592
593
594
 
# File 'lib/mail/message.rb', line 592

def date=( val )
  header[:date] = val
end

- (Object) decode_body 



1818
1819
1820
 
# File 'lib/mail/message.rb', line 1818

def decode_body
  body.decoded
end

- (Object) decoded 



1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
 
# File 'lib/mail/message.rb', line 1797

def decoded
  case
  when self.text?
    decode_body_as_text
  when self.attachment?
    decode_body
  when !self.multipart?
    body.decoded
  else
    raise NoMethodError, 'Can not decode an entire message, try calling #decoded on the various fields and body or parts if it is a multipart message.'
  end
end

- (Object) default(sym, val = nil)

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.



1103
1104
1105
1106
1107
1108
1109
 
# File 'lib/mail/message.rb', line 1103

def default( sym, val = nil )
  if val
    header[sym] = val
  else
    header[sym].default if header[sym]
  end
end

- (Object) deliver

Delivers an mail object.

Examples:

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


226
227
228
229
230
231
232
233
234
235
 
# File 'lib/mail/message.rb', line 226

def deliver
  inform_interceptors
  if delivery_handler
    delivery_handler.deliver_mail(self) { do_delivery }
  else
    do_delivery
  end
  inform_observers
  self
end

- (Object) deliver!

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

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

Returns self



243
244
245
246
247
248
 
# File 'lib/mail/message.rb', line 243

def deliver!
  inform_interceptors
  response = delivery_method.deliver!(self)
  inform_observers
  delivery_method.settings[:return_response] ? response : self
end

- (Object) delivery_method(method = nil, settings = {}) 



250
251
252
253
254
255
256
 
# File 'lib/mail/message.rb', line 250

def delivery_method(method = nil, settings = {})
  unless method
    @delivery_method
  else
    @delivery_method = Configuration.instance.lookup_delivery_method(method).new(settings)
  end
end

- (Object) delivery_status_part

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



1475
1476
1477
 
# File 'lib/mail/message.rb', line 1475

def delivery_status_part
  @delivery_stats_part ||= parts.select { |p| p.delivery_status_report_part? }.first
end

- (Boolean) delivery_status_report?

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

Returns:

  • (Boolean) 


1470
1471
1472
 
# File 'lib/mail/message.rb', line 1470

def delivery_status_report?
  multipart_report? && content_type_parameters['report-type'] =~ /^delivery-status$/i
end

- (Object) destinations

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'


1182
1183
1184
 
# File 'lib/mail/message.rb', line 1182

def destinations
  [to_addrs, cc_addrs, bcc_addrs].compact.flatten
end

- (Object) diagnostic_code 



1495
1496
1497
 
# File 'lib/mail/message.rb', line 1495

def diagnostic_code
  delivery_status_part and delivery_status_part.diagnostic_code
end

- (Object) encode! 



1712
1713
1714
1715
 
# File 'lib/mail/message.rb', line 1712

def encode!
  STDERR.puts("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
  ready_to_send!
end

- (Object) encoded

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.



1720
1721
1722
1723
1724
1725
1726
 
# File 'lib/mail/message.rb', line 1720

def encoded
  ready_to_send!
  buffer = header.encoded
  buffer << "\r\n"
  buffer << body.encoded(content_transfer_encoding)
  buffer
end

- (Object) envelope_date 



393
394
395
 
# File 'lib/mail/message.rb', line 393

def envelope_date
  @envelope ? @envelope.date : nil
end

- (Object) envelope_from 



389
390
391
 
# File 'lib/mail/message.rb', line 389

def envelope_from
  @envelope ? @envelope.from : nil
end

- (Object) error_status 



1491
1492
1493
 
# File 'lib/mail/message.rb', line 1491

def error_status
  delivery_status_part and delivery_status_part.error_status
end

- (Object) errors

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[3] #=> <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.



446
447
448
 
# File 'lib/mail/message.rb', line 446

def errors
  header.errors
end

- (Object) filename

Returns the filename of the attachment



1834
1835
1836
 
# File 'lib/mail/message.rb', line 1834

def filename
  find_attachment
end

- (Object) final_recipient 



1487
1488
1489
 
# File 'lib/mail/message.rb', line 1487

def final_recipient
  delivery_status_part and delivery_status_part.final_recipient
end

- (Object) find_first_mime_type(mt) 



1842
1843
1844
 
# File 'lib/mail/message.rb', line 1842

def find_first_mime_type(mt)
  all_parts.detect { |p| p.mime_type == mt && !p.attachment? }
end

- (Object) from(val = nil)

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


633
634
635
 
# File 'lib/mail/message.rb', line 633

def from( val = nil )
  default :from, val
end

- (Object) from=(val)

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


645
646
647
 
# File 'lib/mail/message.rb', line 645

def from=( val )
  header[:from] = val
end

- (Object) from_addrs

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



1188
1189
1190
 
# File 'lib/mail/message.rb', line 1188

def from_addrs
  from ? [from].flatten : []
end

- (Boolean) has_attachments?

Returns:

  • (Boolean) 


1555
1556
1557
 
# File 'lib/mail/message.rb', line 1555

def has_attachments?
  !attachments.empty?
end

- (Boolean) has_charset?

Returns:

  • (Boolean) 


1323
1324
1325
1326
 
# File 'lib/mail/message.rb', line 1323

def has_charset?
  tmp = header[:content_type].parameters rescue nil
  !!(has_content_type? && tmp && tmp['charset'])
end

- (Boolean) has_content_transfer_encoding?

Returns:

  • (Boolean) 


1328
1329
1330
 
# File 'lib/mail/message.rb', line 1328

def has_content_transfer_encoding?
  header[:content_transfer_encoding] && header[:content_transfer_encoding].errors.blank?
end

- (Boolean) has_content_type?

Returns:

  • (Boolean) 


1318
1319
1320
1321
 
# File 'lib/mail/message.rb', line 1318

def has_content_type?
  tmp = header[:content_type].main_type rescue nil
  !!tmp
end

- (Boolean) has_date?

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

Returns:

  • (Boolean) 


1308
1309
1310
 
# File 'lib/mail/message.rb', line 1308

def has_date?
  header.has_date?
end

- (Boolean) has_message_id?

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.

Returns:

  • (Boolean) 


1302
1303
1304
 
# File 'lib/mail/message.rb', line 1302

def has_message_id?
  header.has_message_id?
end

- (Boolean) has_mime_version?

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

Returns:

  • (Boolean) 


1314
1315
1316
 
# File 'lib/mail/message.rb', line 1314

def has_mime_version?
  header.has_mime_version?
end

- (Boolean) has_transfer_encoding?

:nodoc:

Returns:

  • (Boolean) 


1332
1333
1334
1335
 
# File 'lib/mail/message.rb', line 1332

def has_transfer_encoding? # :nodoc:
  STDERR.puts(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
  has_content_transfer_encoding?
end

- (Object) header(value = nil)

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...


418
419
420
 
# File 'lib/mail/message.rb', line 418

def header(value = nil)
  value ? self.header = value : @header
end

- (Object) header=(value)

Sets the header of the message object.

Example:

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


403
404
405
 
# File 'lib/mail/message.rb', line 403

def header=(value)
  @header = Mail::Header.new(value, charset)
end

- (Object) header_fields

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



1296
1297
1298
 
# File 'lib/mail/message.rb', line 1296

def header_fields
  header.fields
end

- (Object) headers(hash = {})

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



423
424
425
426
427
 
# File 'lib/mail/message.rb', line 423

def headers(hash = {})
  hash.each_pair do |k,v|
    header[k] = v
  end
end

- (Object) html_part(&block)

Accessor for html_part



1560
1561
1562
1563
1564
1565
1566
 
# File 'lib/mail/message.rb', line 1560

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

- (Object) html_part=(msg)

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.



1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
 
# File 'lib/mail/message.rb', line 1580

def html_part=(msg)
  # Assign the html part and set multipart/alternative if there's a text part.
  if msg
    @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

- (Object) in_reply_to(val = nil) 



649
650
651
 
# File 'lib/mail/message.rb', line 649

def in_reply_to( val = nil )
  default :in_reply_to, val
end

- (Object) in_reply_to=(val) 



653
654
655
 
# File 'lib/mail/message.rb', line 653

def in_reply_to=( val )
  header[:in_reply_to] = val
end

- (Object) inform_interceptors 



216
217
218
 
# File 'lib/mail/message.rb', line 216

def inform_interceptors
  Mail.inform_interceptors(self)
end

- (Object) inform_observers 



212
213
214
 
# File 'lib/mail/message.rb', line 212

def inform_observers
  Mail.inform_observers(self)
end

- (Object) inspect 



1793
1794
1795
 
# File 'lib/mail/message.rb', line 1793

def inspect
  "#<#{self.class}:#{self.object_id}, Multipart: #{multipart?}, Headers: #{header.field_summary}>"
end

- (Boolean) is_marked_for_delete?

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.

Returns:

  • (Boolean) 


1871
1872
1873
 
# File 'lib/mail/message.rb', line 1871

def is_marked_for_delete?
  return @mark_for_delete
end

- (Object) keywords(val = nil) 



657
658
659
 
# File 'lib/mail/message.rb', line 657

def keywords( val = nil )
  default :keywords, val
end

- (Object) keywords=(val) 



661
662
663
 
# File 'lib/mail/message.rb', line 661

def keywords=( val )
  header[:keywords] = val
end

- (Object) main_type

Returns the main content type



1439
1440
1441
 
# File 'lib/mail/message.rb', line 1439

def main_type
  has_content_type? ? header[:content_type].main_type : nil rescue nil
end

- (Object) mark_for_delete=(value = true)

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.



1858
1859
1860
 
# File 'lib/mail/message.rb', line 1858

def mark_for_delete=(value = true)
  @mark_for_delete = value
end

- (Object) message_content_type 



1417
1418
1419
1420
 
# File 'lib/mail/message.rb', line 1417

def message_content_type
  STDERR.puts(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
  mime_type
end

- (Object) message_id(val = nil)

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'


678
679
680
 
# File 'lib/mail/message.rb', line 678

def message_id( val = nil )
  default :message_id, val
end

- (Object) message_id=(val)

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'


687
688
689
 
# File 'lib/mail/message.rb', line 687

def message_id=( val )
  header[:message_id] = val
end

- (Object) mime_parameters

Returns the content type parameters



1449
1450
1451
1452
 
# File 'lib/mail/message.rb', line 1449

def mime_parameters
  STDERR.puts(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
  content_type_parameters
end

- (Object) mime_type

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



1413
1414
1415
 
# File 'lib/mail/message.rb', line 1413

def mime_type
  has_content_type? ? header[:content_type].string : nil rescue nil
end

- (Object) mime_version(val = nil)

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'


704
705
706
 
# File 'lib/mail/message.rb', line 704

def mime_version( val = nil )
  default :mime_version, val
end

- (Object) mime_version=(val)

Sets the MIME version of the email by accepting a string

Example:

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


714
715
716
 
# File 'lib/mail/message.rb', line 714

def mime_version=( val )
  header[:mime_version] = val
end

- (Boolean) multipart?

Returns true if the message is multipart

Returns:

  • (Boolean) 


1460
1461
1462
 
# File 'lib/mail/message.rb', line 1460

def multipart?
  has_content_type? ? !!(main_type =~ /^multipart$/i) : false
end

- (Boolean) multipart_report?

Returns true if the message is a multipart/report

Returns:

  • (Boolean) 


1465
1466
1467
 
# File 'lib/mail/message.rb', line 1465

def multipart_report?
  multipart? && sub_type =~ /^report$/i
end

- (Object) part(params = {}) {|new_part| ... }

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

Yields:

  • (new_part) 


1643
1644
1645
1646
1647
 
# File 'lib/mail/message.rb', line 1643

def part(params = {})
  new_part = Part.new(params)
  yield new_part if block_given?
  add_part(new_part)
end

- (Object) parts

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



1513
1514
1515
 
# File 'lib/mail/message.rb', line 1513

def parts
  body.parts
end

- (Object) raw_envelope

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



385
386
387
 
# File 'lib/mail/message.rb', line 385

def raw_envelope
  @raw_envelope
end

- (Object) raw_source

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"


372
373
374
 
# File 'lib/mail/message.rb', line 372

def raw_source
  @raw_source
end

- (Object) read 



1810
1811
1812
1813
1814
1815
1816
 
# File 'lib/mail/message.rb', line 1810

def read
  if self.attachment?
    decode_body
  else
    raise NoMethodError, 'Can not call read on a part unless it is an attachment.'
  end
end

- (Object) ready_to_send!

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



1702
1703
1704
1705
1706
1707
1708
1709
1710
 
# File 'lib/mail/message.rb', line 1702

def ready_to_send!
  identify_and_set_transfer_encoding
  parts.sort!([ "text/plain", "text/enriched", "text/html", "multipart/alternative" ])
  parts.each do |part|
    part.transport_encoding = transport_encoding
    part.ready_to_send!
  end
  add_required_fields
end

- (Object) received(val = nil) 



718
719
720
721
722
723
724
 
# File 'lib/mail/message.rb', line 718

def received( val = nil )
  if val
    header[:received] = val
  else
    header[:received]
  end
end

- (Object) received=(val) 



726
727
728
 
# File 'lib/mail/message.rb', line 726

def received=( val )
  header[:received] = val
end

- (Object) references(val = nil) 



730
731
732
 
# File 'lib/mail/message.rb', line 730

def references( val = nil )
  default :references, val
end

- (Object) references=(val) 



734
735
736
 
# File 'lib/mail/message.rb', line 734

def references=( val )
  header[:references] = val
end

- (Object) register_for_delivery_notification(observer) 



207
208
209
210
 
# File 'lib/mail/message.rb', line 207

def register_for_delivery_notification(observer)
  STDERR.puts("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
  Mail.register_observer(observer)
end

- (Object) remote_mta 



1499
1500
1501
 
# File 'lib/mail/message.rb', line 1499

def remote_mta
  delivery_status_part and delivery_status_part.remote_mta
end

- (Object) reply(*args, &block) 



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/mail/message.rb', line 258

def reply(*args, &block)
  self.class.new.tap do |reply|
    if message_id
      bracketed_message_id = "<#{message_id}>"
      reply.in_reply_to = bracketed_message_id
      if !references.nil?
        refs = [references].flatten.map { |r| "<#{r}>" }
        refs << bracketed_message_id
        reply.references = refs.join(' ')
      elsif !in_reply_to.nil? && !in_reply_to.kind_of?(Array)
        reply.references = "<#{in_reply_to}> #{bracketed_message_id}"
      end
      reply.references ||= bracketed_message_id
    end
    if subject
      reply.subject = subject =~ /^Re:/i ? subject : "RE: #{subject}"
    end
    if reply_to || from
      reply.to = self[reply_to ? :reply_to : :from].to_s
    end
    if to
      reply.from = self[:to].formatted.first.to_s
    end

    unless args.empty?
      if args.flatten.first.respond_to?(:each_pair)
        reply.send(:init_with_hash, args.flatten.first)
      else
        reply.send(:init_with_string, args.flatten[0].to_s.strip)
      end
    end

    if block_given?
      reply.instance_eval(&block)
    end
  end
end

- (Object) reply_to(val = nil)

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


763
764
765
 
# File 'lib/mail/message.rb', line 763

def reply_to( val = nil )
  default :reply_to, val
end

- (Object) reply_to=(val)

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


775
776
777
 
# File 'lib/mail/message.rb', line 775

def reply_to=( val )
  header[:reply_to] = val
end

- (Object) resent_bcc(val = nil)

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


804
805
806
 
# File 'lib/mail/message.rb', line 804

def resent_bcc( val = nil )
  default :resent_bcc, val
end

- (Object) resent_bcc=(val)

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


816
817
818
 
# File 'lib/mail/message.rb', line 816

def resent_bcc=( val )
  header[:resent_bcc] = val
end

- (Object) resent_cc(val = nil)

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


845
846
847
 
# File 'lib/mail/message.rb', line 845

def resent_cc( val = nil )
  default :resent_cc, val
end

- (Object) resent_cc=(val)

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


857
858
859
 
# File 'lib/mail/message.rb', line 857

def resent_cc=( val )
  header[:resent_cc] = val
end

- (Object) resent_date(val = nil) 



861
862
863
 
# File 'lib/mail/message.rb', line 861

def resent_date( val = nil )
  default :resent_date, val
end

- (Object) resent_date=(val) 



865
866
867
 
# File 'lib/mail/message.rb', line 865

def resent_date=( val )
  header[:resent_date] = val
end

- (Object) resent_from(val = nil)

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


894
895
896
 
# File 'lib/mail/message.rb', line 894

def resent_from( val = nil )
  default :resent_from, val
end

- (Object) resent_from=(val)

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


906
907
908
 
# File 'lib/mail/message.rb', line 906

def resent_from=( val )
  header[:resent_from] = val
end

- (Object) resent_message_id(val = nil) 



910
911
912
 
# File 'lib/mail/message.rb', line 910

def resent_message_id( val = nil )
  default :resent_message_id, val
end

- (Object) resent_message_id=(val) 



914
915
916
 
# File 'lib/mail/message.rb', line 914

def resent_message_id=( val )
  header[:resent_message_id] = val
end

- (Object) resent_sender(val = nil)

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'


933
934
935
 
# File 'lib/mail/message.rb', line 933

def resent_sender( val = nil )
  default :resent_sender, val
end

- (Object) resent_sender=(val)

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'


943
944
945
 
# File 'lib/mail/message.rb', line 943

def resent_sender=( val )
  header[:resent_sender] = val
end

- (Object) resent_to(val = nil)

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


972
973
974
 
# File 'lib/mail/message.rb', line 972

def resent_to( val = nil )
  default :resent_to, val
end

- (Object) resent_to=(val)

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


984
985
986
 
# File 'lib/mail/message.rb', line 984

def resent_to=( val )
  header[:resent_to] = val
end

- (Boolean) retryable?

Returns:

  • (Boolean) 


1503
1504
1505
 
# File 'lib/mail/message.rb', line 1503

def retryable?
  delivery_status_part and delivery_status_part.retryable?
end

- (Object) return_path(val = nil)

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



989
990
991
 
# File 'lib/mail/message.rb', line 989

def return_path( val = nil )
  default :return_path, val
end

- (Object) return_path=(val)

Sets the return path of the object



994
995
996
 
# File 'lib/mail/message.rb', line 994

def return_path=( val )
  header[:return_path] = val
end

- (Object) sender(val = nil)

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'


1012
1013
1014
 
# File 'lib/mail/message.rb', line 1012

def sender( val = nil )
  default :sender, val
end

- (Object) sender=(val)

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'


1022
1023
1024
 
# File 'lib/mail/message.rb', line 1022

def sender=( val )
  header[:sender] = val
end

- (Object) set_envelope(val)

Sets the envelope from for the email



377
378
379
380
 
# File 'lib/mail/message.rb', line 377

def set_envelope( val )
  @raw_envelope = val
  @envelope = Mail::Envelope.new( val )
end

- (Object) skip_deletion

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.



1850
1851
1852
 
# File 'lib/mail/message.rb', line 1850

def skip_deletion
  @mark_for_delete = false
end

- (Object) sub_type

Returns the sub content type



1444
1445
1446
 
# File 'lib/mail/message.rb', line 1444

def sub_type
  has_content_type? ? header[:content_type].sub_type : nil rescue nil
end

- (Object) subject(val = nil)

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"


1041
1042
1043
 
# File 'lib/mail/message.rb', line 1041

def subject( val = nil )
  default :subject, val
end

- (Object) subject=(val)

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"


1051
1052
1053
 
# File 'lib/mail/message.rb', line 1051

def subject=( val )
  header[:subject] = val
end

- (Boolean) text?

Returns:

  • (Boolean) 


1875
1876
1877
 
# File 'lib/mail/message.rb', line 1875

def text?
  has_content_type? ? !!(main_type =~ /^text$/i) : false
end

- (Object) text_part(&block)

Accessor for text_part



1569
1570
1571
1572
1573
1574
1575
 
# File 'lib/mail/message.rb', line 1569

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

- (Object) text_part=(msg)

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.



1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
 
# File 'lib/mail/message.rb', line 1602

def text_part=(msg)
  # Assign the text part and set multipart/alternative if there's an html part.
  if msg
    @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

- (Object) to(val = nil)

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


1080
1081
1082
 
# File 'lib/mail/message.rb', line 1080

def to( val = nil )
  default :to, val
end

- (Object) to=(val)

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


1092
1093
1094
 
# File 'lib/mail/message.rb', line 1092

def to=( val )
  header[:to] = val
end

- (Object) to_addrs

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



1194
1195
1196
 
# File 'lib/mail/message.rb', line 1194

def to_addrs
  to ? [to].flatten : []
end

- (Object) to_s 



1789
1790
1791
 
# File 'lib/mail/message.rb', line 1789

def to_s
  encoded
end

- (Object) to_yaml(opts = {}) 



1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
 
# File 'lib/mail/message.rb', line 1743

def to_yaml(opts = {})
  hash = {}
  hash['headers'] = {}
  header.fields.each do |field|
    hash['headers'][field.name] = field.value
  end
  hash['delivery_handler'] = delivery_handler.to_s if delivery_handler
  hash['transport_encoding'] = transport_encoding.to_s
  special_variables = [:@header, :@delivery_handler, :@transport_encoding]
  if multipart?
    hash['multipart_body'] = []
    body.parts.map { |part| hash['multipart_body'] << part.to_yaml }
    special_variables.push(:@body, :@text_part, :@html_part)
  end
  (instance_variables.map(&:to_sym) - special_variables).each do |var|
    hash[var.to_s] = instance_variable_get(var)
  end
  hash.to_yaml(opts)
end

- (Object) transfer_encoding

:nodoc:



1407
1408
1409
1410
 
# File 'lib/mail/message.rb', line 1407

def transfer_encoding # :nodoc:
  STDERR.puts(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
  content_transfer_encoding
end

- (Object) transport_encoding(val = nil) 



596
597
598
599
600
601
602
 
# File 'lib/mail/message.rb', line 596

def transport_encoding( val = nil)
  if val
    self.transport_encoding = val
  else
    @transport_encoding
  end
end

- (Object) transport_encoding=(val) 



604
605
606
 
# File 'lib/mail/message.rb', line 604

def transport_encoding=( val )
  @transport_encoding = Mail::Encodings.get_encoding(val)
end

- (Object) without_attachments! 



1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
 
# File 'lib/mail/message.rb', line 1728

def without_attachments!
  return self unless has_attachments?

  parts.delete_if { |p| p.attachment? }
  body_raw = if parts.empty?
               ''
             else
               body.encoded
             end

  @body = Mail::Body.new(body_raw)

  self
end