Class: Mail::Message

Inherits:
Object
  • 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 contians 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

Constants included from Patterns

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

Instance Method Summary collapse

Methods included from Utilities

included

Methods included from Patterns

included

Constructor Details

#initialize(*args, &block) ⇒ Message

Creates a new Mail::Message object through .new



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/mail/message.rb', line 51

def initialize(*args, &block)
  @body = nil

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

  if block_given?
    instance_eval(&block)
  end

  self
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &block) ⇒ Object

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



890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
 
# File 'lib/mail/message.rb', line 890

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 Method Details

#<=>(other) ⇒ Object 



71
72
73
74
75
76
77
 
# File 'lib/mail/message.rb', line 71

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

#==(other) ⇒ Object 



79
80
81
82
83
84
85
 
# File 'lib/mail/message.rb', line 79

def ==(other)
  unless other.respond_to?(:encoded)
    false
  else
    self.encoded == other.encoded
  end
end

#[](name) ⇒ Object

Allows you to read an arbitrary header

Example:

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



847
848
849
 
# File 'lib/mail/message.rb', line 847

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

#[]=(name, value) ⇒ Object

Allows you to add an arbitrary header

Example:

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



831
832
833
834
835
836
837
838
839
 
# File 'lib/mail/message.rb', line 831

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

#action ⇒ Object 



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

def action
  delivery_status_part.action
end

#add_charset ⇒ Object

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

Otherwise raises a warning



988
989
990
991
992
993
994
995
996
 
# File 'lib/mail/message.rb', line 988

def add_charset
  if body.only_us_ascii?
    header[:content_type].parameters['charset'] = 'US-ASCII'
  else
    warning = "Non US-ASCII detected and no charset defined.\nDefaulting to UTF-8, set your own if this is incorrect.\nCalled from:\n#{caller.join("\n")}"
    STDERR.puts(warning)
    header[:content_type].parameters['charset'] = 'UTF-8'
  end
end

#add_content_transfer_encoding ⇒ Object

Adds a content transfer encoding

Otherwise raises a warning



1001
1002
1003
1004
1005
1006
1007
1008
1009
 
# File 'lib/mail/message.rb', line 1001

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.\nCalled from:\n#{caller.join("\n")}"
    STDERR.puts(warning)
    header[:content_transfer_encoding] = '8bit'
  end
end

#add_content_type ⇒ Object

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

Otherwise raises a warning



981
982
983
 
# File 'lib/mail/message.rb', line 981

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

#add_date(date_val = '') ⇒ Object

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.



964
965
966
 
# File 'lib/mail/message.rb', line 964

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

#add_file(options) ⇒ Object

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 type, or you can pass in the filename as a string, and pass in the file data as a blob.

Example:

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

or

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

The above two alternatives will produce the same email message.

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 it’s 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'



1247
1248
1249
1250
1251
1252
1253
1254
1255
 
# File 'lib/mail/message.rb', line 1247

def add_file(options)
  convert_to_multipart unless self.multipart? || self.body.decoded.blank?
  add_multipart_mixed_header
  if options.is_a?(Hash)
    self.body << Mail::Part.new(options)
  else
    self.body << Mail::Part.new(:filename => options)
  end
end

#add_message_id(msg_id_val = '') ⇒ Object

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.



954
955
956
 
# File 'lib/mail/message.rb', line 954

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

#add_mime_version(ver_val = '') ⇒ Object

Creates a new empty Mime Version field and inserts it in the correct order into the Header. The MimeVersion 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.



974
975
976
 
# File 'lib/mail/message.rb', line 974

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

#add_part(part) ⇒ Object

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



1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
 
# File 'lib/mail/message.rb', line 1189

def add_part(part)
  if body.parts.empty? && !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

#add_transfer_encoding ⇒ Object

:nodoc:



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

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

#attachment ⇒ Object

Returns the attachment data if there is any



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

def attachment
  @attachment
end

#attachment? ⇒ Boolean

Returns true if this part is an attachment

Returns:

  • (Boolean) 


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

def attachment?
  find_attachment
end

#attachments ⇒ Object

Returns an array of attachments in the email recursively



1126
1127
1128
1129
1130
1131
1132
1133
1134
 
# File 'lib/mail/message.rb', line 1126

def attachments
  body.parts.map do |p| 
    if p.parts.empty?
      p.attachment if p.attachment?
    else
      p.attachments
    end
  end.compact.flatten
end

#bcc(val = nil) ⇒ Object

Returns the Bcc value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Bcc.

Example:

mail.bcc = 'Mikel <[email protected]>'
mail.bcc #=> '[email protected]'
mail.bcc = 'Mikel <[email protected]>, [email protected]'
mail.bcc #=> ['[email protected]', '[email protected]']

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

Example:

mail.bcc 'Mikel <[email protected]>'
mail.bcc #=> '[email protected]'



172
173
174
 
# File 'lib/mail/message.rb', line 172

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

#bcc=(val) ⇒ Object

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

Example:

mail.bcc = 'Mikel <[email protected]>'
mail.bcc #=> '[email protected]'
mail.bcc = 'Mikel <[email protected]>, [email protected]'
mail.bcc #=> ['[email protected]', '[email protected]']



184
185
186
 
# File 'lib/mail/message.rb', line 184

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

#bcc_addrs ⇒ Object

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



821
822
823
 
# File 'lib/mail/message.rb', line 821

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

#body(value = nil) ⇒ Object

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



778
779
780
781
782
783
784
785
 
# File 'lib/mail/message.rb', line 778

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

#body=(value) ⇒ Object

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'



756
757
758
759
760
761
762
763
764
765
766
 
# File 'lib/mail/message.rb', line 756

def body=(value)
  case
  when value == nil
    @body = Mail::Body.new('')
  when @body && !@body.parts.empty?
    @body << Mail::Part.new(value)
  else
    @body = Mail::Body.new(value)
  end
  add_encoding_to_body
end

#bounced? ⇒ Boolean

Returns:

  • (Boolean) 


1087
1088
1089
 
# File 'lib/mail/message.rb', line 1087

def bounced?
  delivery_status_part.bounced?
end

#boundary ⇒ Object

Returns the current boundary for this message part



1116
1117
1118
 
# File 'lib/mail/message.rb', line 1116

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

#cc(val = nil) ⇒ Object

Returns the Cc value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Cc.

Example:

mail.cc = 'Mikel <[email protected]>'
mail.cc #=> '[email protected]'
mail.cc = 'Mikel <[email protected]>, [email protected]'
mail.cc #=> ['[email protected]', '[email protected]']

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

Example:

mail.cc 'Mikel <[email protected]>'
mail.cc #=> '[email protected]'



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

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

#cc=(val) ⇒ Object

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

Example:

mail.cc = 'Mikel <[email protected]>'
mail.cc #=> '[email protected]'
mail.cc = 'Mikel <[email protected]>, [email protected]'
mail.cc #=> ['[email protected]', '[email protected]']



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

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

#cc_addrs ⇒ Object

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



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

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

#charset ⇒ Object

Returns the character set defined in the content type field



1032
1033
1034
 
# File 'lib/mail/message.rb', line 1032

def charset
  content_type ? content_type_parameters['charset'] : nil
end

#charset=(value) ⇒ Object

Sets the charset to the supplied value. Will set the content type to text/plain if it does not already exist



1038
1039
1040
1041
1042
1043
1044
 
# File 'lib/mail/message.rb', line 1038

def charset=(value)
  if content_type
    content_type_parameters['charset'] = value
  else
    self.content_type ['text', 'plain', {'charset' => value}]
  end
end

#comments(val = nil) ⇒ Object 



221
222
223
 
# File 'lib/mail/message.rb', line 221

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

#comments=(val) ⇒ Object 



225
226
227
 
# File 'lib/mail/message.rb', line 225

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

#content_description(val = nil) ⇒ Object 



229
230
231
 
# File 'lib/mail/message.rb', line 229

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

#content_description=(val) ⇒ Object 



233
234
235
 
# File 'lib/mail/message.rb', line 233

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

#content_disposition(val = nil) ⇒ Object 



237
238
239
 
# File 'lib/mail/message.rb', line 237

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

#content_disposition=(val) ⇒ Object 



241
242
243
 
# File 'lib/mail/message.rb', line 241

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

#content_id(val = nil) ⇒ Object 



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

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

#content_id=(val) ⇒ Object 



249
250
251
 
# File 'lib/mail/message.rb', line 249

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

#content_location(val = nil) ⇒ Object 



253
254
255
 
# File 'lib/mail/message.rb', line 253

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

#content_location=(val) ⇒ Object 



257
258
259
 
# File 'lib/mail/message.rb', line 257

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

#content_transfer_encoding(val = nil) ⇒ Object 



261
262
263
 
# File 'lib/mail/message.rb', line 261

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

#content_transfer_encoding=(val) ⇒ Object 



265
266
267
 
# File 'lib/mail/message.rb', line 265

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

#content_type(val = nil) ⇒ Object 



269
270
271
 
# File 'lib/mail/message.rb', line 269

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

#content_type=(val) ⇒ Object 



273
274
275
 
# File 'lib/mail/message.rb', line 273

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

#content_type_parameters ⇒ Object

Returns the content type parameters



1063
1064
1065
 
# File 'lib/mail/message.rb', line 1063

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

#convert_to_multipart ⇒ Object 



1257
1258
1259
1260
1261
1262
1263
 
# File 'lib/mail/message.rb', line 1257

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

#date(val = nil) ⇒ Object 



277
278
279
 
# File 'lib/mail/message.rb', line 277

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

#date=(val) ⇒ Object 



281
282
283
 
# File 'lib/mail/message.rb', line 281

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

#decoded ⇒ Object

Raises:

  • (NoMethodError) 


1292
1293
1294
 
# File 'lib/mail/message.rb', line 1292

def decoded
  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

#default(sym, val = nil) ⇒ Object

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.



723
724
725
726
727
728
729
 
# File 'lib/mail/message.rb', line 723

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

#deliver! ⇒ Object 



67
68
69
 
# File 'lib/mail/message.rb', line 67

def deliver!
  Deliverable.perform_delivery!(self)
end

#delivery_status_part ⇒ Object

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



1083
1084
1085
 
# File 'lib/mail/message.rb', line 1083

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

#delivery_status_report? ⇒ Boolean

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

Returns:

  • (Boolean) 


1078
1079
1080
 
# File 'lib/mail/message.rb', line 1078

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

#destinations ⇒ Object

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 = '[email protected]'
mail.cc = '[email protected]'
mail.bcc = '[email protected]'
mail.destinations.length #=> 3
mail.destinations.first #=> '[email protected]'



797
798
799
 
# File 'lib/mail/message.rb', line 797

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

#diagnostic_code ⇒ Object 



1103
1104
1105
 
# File 'lib/mail/message.rb', line 1103

def diagnostic_code
  delivery_status_part.diagnostic_code
end

#encode! ⇒ Object 



1272
1273
1274
1275
 
# File 'lib/mail/message.rb', line 1272

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

#encoded ⇒ Object

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.



1280
1281
1282
1283
1284
1285
1286
 
# File 'lib/mail/message.rb', line 1280

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

#envelope_date ⇒ Object 



119
120
121
 
# File 'lib/mail/message.rb', line 119

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

#envelope_from ⇒ Object 



115
116
117
 
# File 'lib/mail/message.rb', line 115

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

#error_status ⇒ Object 



1099
1100
1101
 
# File 'lib/mail/message.rb', line 1099

def error_status
  delivery_status_part.error_status
end

#filename ⇒ Object

Returns the filename of the attachment



1307
1308
1309
1310
1311
1312
1313
 
# File 'lib/mail/message.rb', line 1307

def filename
  if attachment?
    attachment.filename
  else
    nil
  end
end

#final_recipient ⇒ Object 



1095
1096
1097
 
# File 'lib/mail/message.rb', line 1095

def final_recipient
  delivery_status_part.final_recipient
end

#from(val = nil) ⇒ Object

Returns the From value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the From.

Example:

mail.from = 'Mikel <[email protected]>'
mail.from #=> '[email protected]'
mail.from = 'Mikel <[email protected]>, [email protected]'
mail.from #=> ['[email protected]', '[email protected]']

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

Example:

mail.from 'Mikel <[email protected]>'
mail.from #=> '[email protected]'



302
303
304
 
# File 'lib/mail/message.rb', line 302

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

#from=(val) ⇒ Object

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

Example:

mail.from = 'Mikel <[email protected]>'
mail.from #=> '[email protected]'
mail.from = 'Mikel <[email protected]>, [email protected]'
mail.from #=> ['[email protected]', '[email protected]']



314
315
316
 
# File 'lib/mail/message.rb', line 314

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

#from_addrs ⇒ Object

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



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

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

#has_attachments? ⇒ Boolean

Returns:

  • (Boolean) 


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

def has_attachments?
  !attachments.empty?
end

#has_charset? ⇒ Boolean

Returns:

  • (Boolean) 


935
936
937
 
# File 'lib/mail/message.rb', line 935

def has_charset?
  !!charset
end

#has_content_transfer_encoding? ⇒ Boolean

Returns:

  • (Boolean) 


939
940
941
 
# File 'lib/mail/message.rb', line 939

def has_content_transfer_encoding?
  !!content_transfer_encoding
end

#has_content_type? ⇒ Boolean

Returns:

  • (Boolean) 


931
932
933
 
# File 'lib/mail/message.rb', line 931

def has_content_type?
  !!content_type
end

#has_date? ⇒ Boolean

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) 


921
922
923
 
# File 'lib/mail/message.rb', line 921

def has_date?
  header.has_date?
end

#has_message_id? ⇒ Boolean

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) 


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

def has_message_id?
  header.has_message_id?
end

#has_mime_version? ⇒ Boolean

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) 


927
928
929
 
# File 'lib/mail/message.rb', line 927

def has_mime_version?
  header.has_mime_version?
end

#has_transfer_encoding? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


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

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

#header(value = nil) ⇒ Object

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



144
145
146
 
# File 'lib/mail/message.rb', line 144

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

#header=(value) ⇒ Object

Sets the header of the message object.

Example:

mail.header = 'To: [email protected]\r\nFrom: [email protected]'
mail.header #=> <#Mail::Header



129
130
131
 
# File 'lib/mail/message.rb', line 129

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

#header_fields ⇒ Object

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



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

def header_fields
  header.fields
end

#headers(hash = {}) ⇒ Object

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



149
150
151
152
153
 
# File 'lib/mail/message.rb', line 149

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

#html_part(&block) ⇒ Object

Accessor for html_part



1141
1142
1143
1144
1145
1146
1147
1148
1149
 
# File 'lib/mail/message.rb', line 1141

def html_part(&block)
  if block_given?
    @html_part = Mail::Part.new(&block)
    add_multipart_alternate_header
    add_part(@html_part)
  else
    @html_part
  end
end

#html_part=(msg = nil) ⇒ Object

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.



1165
1166
1167
1168
1169
1170
1171
1172
1173
 
# File 'lib/mail/message.rb', line 1165

def html_part=(msg = nil)
  if msg
    @html_part = msg
  else
    @html_part = Mail::Part.new('Content-Type: text/html;')
  end
  add_multipart_alternate_header
  add_part(@html_part)
end

#in_reply_to(val = nil) ⇒ Object 



318
319
320
 
# File 'lib/mail/message.rb', line 318

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

#in_reply_to=(val) ⇒ Object 



322
323
324
 
# File 'lib/mail/message.rb', line 322

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

#keywords(val = nil) ⇒ Object 



326
327
328
 
# File 'lib/mail/message.rb', line 326

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

#keywords=(val) ⇒ Object 



330
331
332
 
# File 'lib/mail/message.rb', line 330

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

#main_type ⇒ Object

Returns the main content type



1047
1048
1049
 
# File 'lib/mail/message.rb', line 1047

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

#message_content_type ⇒ Object 



1026
1027
1028
1029
 
# File 'lib/mail/message.rb', line 1026

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

#message_id(val = nil) ⇒ Object

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 = '<[email protected]>'
mail.message_id #=> '[email protected]'

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

mail.message_id '<[email protected]>'
mail.message_id #=> '[email protected]'



347
348
349
 
# File 'lib/mail/message.rb', line 347

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

#message_id=(val) ⇒ Object

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 = '<[email protected]>'
mail.message_id #=> '[email protected]'



356
357
358
 
# File 'lib/mail/message.rb', line 356

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

#mime_parameters ⇒ Object

Returns the content type parameters



1057
1058
1059
1060
 
# File 'lib/mail/message.rb', line 1057

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

#mime_type ⇒ Object

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



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

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

#mime_version(val = nil) ⇒ Object

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'



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

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

#mime_version=(val) ⇒ Object

Sets the mime version of the email by accepting a string

Example:

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



383
384
385
 
# File 'lib/mail/message.rb', line 383

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

#multipart? ⇒ Boolean

Returns true if the message is multipart

Returns:

  • (Boolean) 


1068
1069
1070
 
# File 'lib/mail/message.rb', line 1068

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

#multipart_report? ⇒ Boolean

Returns true if the message is a multipart/report

Returns:

  • (Boolean) 


1073
1074
1075
 
# File 'lib/mail/message.rb', line 1073

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

#part(params = {}) {|new_part| ... } ⇒ Object

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) 


1210
1211
1212
1213
1214
 
# File 'lib/mail/message.rb', line 1210

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

#parts ⇒ Object

Returns an array of parts in the message



1121
1122
1123
 
# File 'lib/mail/message.rb', line 1121

def parts
  body.parts
end

#raw_envelope ⇒ Object

The raw_envelope is the From [email protected] 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



111
112
113
 
# File 'lib/mail/message.rb', line 111

def raw_envelope
  @raw_envelope
end

#raw_source ⇒ Object

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"



95
96
97
 
# File 'lib/mail/message.rb', line 95

def raw_source
  @raw_source
end

#raw_source=(value) ⇒ Object 



99
100
101
 
# File 'lib/mail/message.rb', line 99

def raw_source=(value)
  @raw_source = value.to_crlf
end

#ready_to_send! ⇒ Object

Encodes the message, calls encode on all it’s parts, gets an email message ready to send



1267
1268
1269
1270
 
# File 'lib/mail/message.rb', line 1267

def ready_to_send!
  parts.each { |part| part.ready_to_send! }
  add_required_fields
end

#received(val = nil) ⇒ Object 



387
388
389
390
391
392
393
 
# File 'lib/mail/message.rb', line 387

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

#received=(val) ⇒ Object 



395
396
397
 
# File 'lib/mail/message.rb', line 395

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

#references(val = nil) ⇒ Object 



399
400
401
 
# File 'lib/mail/message.rb', line 399

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

#references=(val) ⇒ Object 



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

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

#remote_mta ⇒ Object 



1107
1108
1109
 
# File 'lib/mail/message.rb', line 1107

def remote_mta
  delivery_status_part.remote_mta
end

#reply_to(val = nil) ⇒ Object

Returns the Reply-To value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Reply-To.

Example:

mail.reply_to = 'Mikel <[email protected]>'
mail.reply_to #=> '[email protected]'
mail.reply_to = 'Mikel <[email protected]>, [email protected]'
mail.reply_to #=> ['[email protected]', '[email protected]']

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

Example:

mail.reply_to 'Mikel <[email protected]>'
mail.reply_to #=> '[email protected]'



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

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

#reply_to=(val) ⇒ Object

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

Example:

mail.reply_to = 'Mikel <[email protected]>'
mail.reply_to #=> '[email protected]'
mail.reply_to = 'Mikel <[email protected]>, [email protected]'
mail.reply_to #=> ['[email protected]', '[email protected]']



436
437
438
 
# File 'lib/mail/message.rb', line 436

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

#resent_bcc(val = nil) ⇒ Object

Returns the Resent-Bcc value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Resent-Bcc.

Example:

mail.resent_bcc = 'Mikel <[email protected]>'
mail.resent_bcc #=> '[email protected]'
mail.resent_bcc = 'Mikel <[email protected]>, [email protected]'
mail.resent_bcc #=> ['[email protected]', '[email protected]']

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

Example:

mail.resent_bcc 'Mikel <[email protected]>'
mail.resent_bcc #=> '[email protected]'



457
458
459
 
# File 'lib/mail/message.rb', line 457

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

#resent_bcc=(val) ⇒ Object

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

Example:

mail.resent_bcc = 'Mikel <[email protected]>'
mail.resent_bcc #=> '[email protected]'
mail.resent_bcc = 'Mikel <[email protected]>, [email protected]'
mail.resent_bcc #=> ['[email protected]', '[email protected]']



469
470
471
 
# File 'lib/mail/message.rb', line 469

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

#resent_cc(val = nil) ⇒ Object

Returns the Resent-Cc value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Resent-Cc.

Example:

mail.resent_cc = 'Mikel <[email protected]>'
mail.resent_cc #=> '[email protected]'
mail.resent_cc = 'Mikel <[email protected]>, [email protected]'
mail.resent_cc #=> ['[email protected]', '[email protected]']

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

Example:

mail.resent_cc 'Mikel <[email protected]>'
mail.resent_cc #=> '[email protected]'



490
491
492
 
# File 'lib/mail/message.rb', line 490

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

#resent_cc=(val) ⇒ Object

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

Example:

mail.resent_cc = 'Mikel <[email protected]>'
mail.resent_cc #=> '[email protected]'
mail.resent_cc = 'Mikel <[email protected]>, [email protected]'
mail.resent_cc #=> ['[email protected]', '[email protected]']



502
503
504
 
# File 'lib/mail/message.rb', line 502

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

#resent_date(val = nil) ⇒ Object 



506
507
508
 
# File 'lib/mail/message.rb', line 506

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

#resent_date=(val) ⇒ Object 



510
511
512
 
# File 'lib/mail/message.rb', line 510

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

#resent_from(val = nil) ⇒ Object

Returns the Resent-From value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Resent-From.

Example:

mail.resent_from = 'Mikel <[email protected]>'
mail.resent_from #=> '[email protected]'
mail.resent_from = 'Mikel <[email protected]>, [email protected]'
mail.resent_from #=> ['[email protected]', '[email protected]']

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

Example:

mail.resent_from 'Mikel <[email protected]>'
mail.resent_from #=> '[email protected]'



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

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

#resent_from=(val) ⇒ Object

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

Example:

mail.resent_from = 'Mikel <[email protected]>'
mail.resent_from #=> '[email protected]'
mail.resent_from = 'Mikel <[email protected]>, [email protected]'
mail.resent_from #=> ['[email protected]', '[email protected]']



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

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

#resent_message_id(val = nil) ⇒ Object 



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

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

#resent_message_id=(val) ⇒ Object 



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

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

#resent_sender(val = nil) ⇒ Object

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

Example:

mail.resent_sender = 'Mikel <[email protected]>'
mail.resent_sender #=> '[email protected]'

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

Example:

mail.resent_sender 'Mikel <[email protected]>'
mail.resent_sender #=> '[email protected]'



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

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

#resent_sender=(val) ⇒ Object

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

Example:

mail.sender = 'Mikel <[email protected]>'
mail.sender #=> '[email protected]'



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

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

#resent_to(val = nil) ⇒ Object

Returns the Resent-To value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the Resent-To.

Example:

mail.resent_to = 'Mikel <[email protected]>'
mail.resent_to #=> '[email protected]'
mail.resent_to = 'Mikel <[email protected]>, [email protected]'
mail.resent_to #=> ['[email protected]', '[email protected]']

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

Example:

mail.resent_to 'Mikel <[email protected]>'
mail.resent_to #=> '[email protected]'



600
601
602
 
# File 'lib/mail/message.rb', line 600

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

#resent_to=(val) ⇒ Object

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

Example:

mail.resent_to = 'Mikel <[email protected]>'
mail.resent_to #=> '[email protected]'
mail.resent_to = 'Mikel <[email protected]>, [email protected]'
mail.resent_to #=> ['[email protected]', '[email protected]']



612
613
614
 
# File 'lib/mail/message.rb', line 612

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

#retryable? ⇒ Boolean

Returns:

  • (Boolean) 


1111
1112
1113
 
# File 'lib/mail/message.rb', line 1111

def retryable?
  delivery_status_part.retryable?
end

#return_path(val = nil) ⇒ Object

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



617
618
619
 
# File 'lib/mail/message.rb', line 617

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

#return_path=(val) ⇒ Object

Sets the return path of the object



622
623
624
 
# File 'lib/mail/message.rb', line 622

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

#sender(val = nil) ⇒ Object

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 <[email protected]>'
mail.sender #=> '[email protected]'

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

Example:

mail.sender 'Mikel <[email protected]>'
mail.sender #=> '[email protected]'



640
641
642
 
# File 'lib/mail/message.rb', line 640

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

#sender=(val) ⇒ Object

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

Example:

mail.sender = 'Mikel <[email protected]>'
mail.sender #=> '[email protected]'



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

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

#set_envelope(val) ⇒ Object 



103
104
105
106
 
# File 'lib/mail/message.rb', line 103

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

#sub_type ⇒ Object

Returns the sub content type



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

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

#subject(val = nil) ⇒ Object

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"



669
670
671
 
# File 'lib/mail/message.rb', line 669

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

#subject=(val) ⇒ Object

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"



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

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

#text_part(&block) ⇒ Object

Accessor for text_part



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

def text_part(&block)
  if block_given?
    @text_part = Mail::Part.new(&block)
    add_multipart_alternate_header
    add_part(@text_part)
  else
    @text_part
  end
end

#text_part=(msg = nil) ⇒ Object

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.



1178
1179
1180
1181
1182
1183
1184
1185
1186
 
# File 'lib/mail/message.rb', line 1178

def text_part=(msg = nil)
  if msg
    @text_part = msg
  else
    @text_part = Mail::Part.new('Content-Type: text/plain;')
  end
  add_multipart_alternate_header
  add_part(@text_part)
end

#to(val = nil) ⇒ Object

Returns the To value of the mail object, either a single string of an address spec or an array of strings of address specs if there is more than one address in the To.

Example:

mail.to = 'Mikel <[email protected]>'
mail.to #=> '[email protected]'
mail.to = 'Mikel <[email protected]>, [email protected]'
mail.to #=> ['[email protected]', '[email protected]']

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

Example:

mail.to 'Mikel <[email protected]>'
mail.to #=> '[email protected]'



700
701
702
 
# File 'lib/mail/message.rb', line 700

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

#to=(val) ⇒ Object

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

Example:

mail.to = 'Mikel <[email protected]>'
mail.to #=> '[email protected]'
mail.to = 'Mikel <[email protected]>, [email protected]'
mail.to #=> ['[email protected]', '[email protected]']



712
713
714
 
# File 'lib/mail/message.rb', line 712

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

#to_addrs ⇒ Object

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



809
810
811
 
# File 'lib/mail/message.rb', line 809

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

#to_s ⇒ Object 



1288
1289
1290
 
# File 'lib/mail/message.rb', line 1288

def to_s
  encoded
end

#transfer_encoding ⇒ Object

:nodoc:



1016
1017
1018
1019
 
# File 'lib/mail/message.rb', line 1016

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