Accessing a TMail object done via the TMail::Mail class. As email can be fairly complex creatures, you will find a large amount of accessor and setter methods in this class!
Most of the below methods handle the header, in fact, what TMail does best is handle the header of the email object. There are only a few methods that deal directly with the body of the email, such as base64_encode and base64_decode.
The usual way is to install the gem (see the {README}[README] on how to do this) and then put at the top of your class:
require 'tmail'
You can then create a new TMail object in your code with:
@email = TMail::Mail.new
Or if you have an email as a string, you can initialize a new TMail::Mail object and get it to parse that string for you like so:
@email = TMail::Mail.parse(email_text)
You can also read a single email off the disk, for example:
@email = TMail::Mail.load('filename.txt')
Also, you can read a mailbox (usual unix mbox format) and end up with an array of TMail objects by doing something like this:
# Note, we pass true as the last variable to open the mailbox read only mailbox = TMail::UNIXMbox.new("mailbox", nil, true) @emails = [] mailbox.each_port { |m| @emails << TMail::Mail.new(m) }
ALLOW_MULTIPLE | = | { 'received' => true, 'resent-date' => true, 'resent-from' => true, 'resent-sender' => true, 'resent-to' => true, 'resent-cc' => true, 'resent-bcc' => true, 'resent-message-id' => true, 'comments' => true, 'keywords' => true | header | |
USE_ARRAY | = | ALLOW_MULTIPLE | ||
FIELD_ORDER | = | %w( return-path received resent-date resent-from resent-sender resent-to resent-cc resent-bcc resent-message-id date from sender reply-to to cc bcc message-id in-reply-to references subject comments keywords mime-version content-type content-transfer-encoding content-disposition content-description ) | ||
NOSEND_FIELDS | = | %w( received bcc ) |
load | -> | load_from |
load | -> | loadfrom |
Opens an email that has been saved out as a file by itself.
This function will read a file non-destructively and then parse the contents and return a TMail::Mail object.
Does not handle multiple email mailboxes (like a unix mbox) for that use the TMail::UNIXMbox class.
Example:
mail = TMail::Mail.load('filename')
Parses an email from the supplied string and returns a TMail::Mail object.
Example:
require 'rubygems'; require 'tmail' email_string =<<HEREDOC To: mikel@lindsaar.net From: mikel@me.com Subject: This is a short Email Hello there Mikel! HEREDOC mail = TMail::Mail.parse(email_string) #=> #<TMail::Mail port=#<TMail::StringPort:id=0xa30ac0> bodyport=nil> mail.body #=> "Hello there Mikel!\n\n"
Returns a TMail::AddressHeader object of the field you are querying. Examples:
@mail['from'] #=> #<TMail::AddressHeader "mikel@test.com.au"> @mail['to'] #=> #<TMail::AddressHeader "mikel@test.com.au">
You can get the string value of this by passing "to_s" to the query: Example:
@mail['to'].to_s #=> "mikel@test.com.au"
Allows you to set or delete TMail header objects at will. Examples:
@mail = TMail::Mail.new @mail['to'].to_s # => 'mikel@test.com.au' @mail['to'] = 'mikel@elsewhere.org' @mail['to'].to_s # => 'mikel@elsewhere.org' @mail.encoded # => "To: mikel@elsewhere.org\r\n\r\n" @mail['to'] = nil @mail['to'].to_s # => nil @mail.encoded # => "\r\n"
Note: setting mail[] = nil actually deletes the header field in question from the object, it does not just set the value of the hash to nil
Returns the result of decoding the TMail::Mail object body without altering the current body
Return the result of encoding the TMail::Mail object body without altering the current body
Returns who the email bcc‘d as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns
Example:
mail = TMail::Mail.new mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.bcc #=> ["mikel@me.org", "mikel@you.org"]
Destructively sets the "Bcc:" field to the passed array of strings (which should be valid email addresses)
Example:
mail = TMail::Mail.new mail.bcc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"] mail.bcc #=> ["mikel@abc.org", "mikel@xyz.org"] mail['bcc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
Return a TMail::Addresses instance for each entry in the "Bcc:" field of the mail object header.
If the "Bcc:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.bcc_addrs #=> nil mail.bcc_addrs([]) #=> [] mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.bcc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively set the to field of the "Bcc:" header to equal the passed in string.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.bcc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Returns who the email cc‘d as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns
Example:
mail = TMail::Mail.new mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.cc #=> ["mikel@me.org", "mikel@you.org"]
Destructively sets the "Cc:" field to the passed array of strings (which should be valid email addresses)
Example:
mail = TMail::Mail.new mail.cc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"] mail.cc #=> ["mikel@abc.org", "mikel@xyz.org"] mail['cc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
Return a TMail::Addresses instance for each entry in the "Cc:" field of the mail object header.
If the "Cc:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.cc_addrs #=> nil mail.cc_addrs([]) #=> [] mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.cc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively set the to field of the "Cc:" header to equal the passed in string.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.cc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Returns the character set of the email. Returns nil if no encoding set or returns whatever default you pass as a parameter - note passing the parameter does NOT change the mail object in any way.
Example:
mail = TMail::Mail.load("path_to/utf8_email") mail.charset #=> "UTF-8" mail = TMail::Mail.new mail.charset #=> nil mail.charset("US-ASCII") #=> "US-ASCII"
Destructively sets the character set used by this mail object to the passed string, you should note though that this does nothing to the mail body, just changes the header value, you will need to transliterate the body as well to match whatever you put in this header value if you are changing character sets.
Example:
mail = TMail::Mail.new mail.charset #=> nil mail.charset = "UTF-8" mail.charset #=> "UTF-8"
Returns the current "Content-Type" of the mail instance.
If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.content_type #=> nil mail.content_type([]) #=> [] mail = TMail::Mail.load("../test/fixtures/raw_email") mail.content_type #=> "text/plain"
Returns true if this part‘s content main type is text, else returns false. By main type is meant "text/plain" is text. "text/html" is text
Creates a new email in reply to self. Sets the In-Reply-To and References headers for you automagically.
Example:
mail = TMail::Mail.load("my_email") forward_email = mail.create_forward forward_email.class #=> TMail::Mail forward_email.content_type #=> "multipart/mixed" forward_email.body #=> "Attachment: (unnamed)" forward_email.encoded #=> Returns the original email as a MIME attachment
Creates a new email in reply to self. Sets the In-Reply-To and References headers for you automagically.
Example:
mail = TMail::Mail.load("my_email") reply_email = mail.create_reply reply_email.class #=> TMail::Mail reply_email.references #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"] reply_email.in_reply_to #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
Returns the content-disposition of the mail object, returns nil or the passed default value if given
Example:
mail = TMail::Mail.load("path_to/raw_mail_with_attachment") mail.disposition #=> "attachment" mail = TMail::Mail.load("path_to/plain_simple_email") mail.disposition #=> nil mail.disposition(false) #=> false
Returns true if the content type of this part of the email is a disposition attachment
Returns the value of a parameter in an existing content-disposition header
Example:
mail.set_disposition("attachment", {:filename => "test.rb"}) mail['content-disposition'].to_s #=> "attachment; filename=test.rb" mail.disposition_param("filename") #=> "test.rb" mail.disposition_param("missing_param_key") #=> nil mail.disposition_param("missing_param_key", false) #=> false mail.disposition_param("missing_param_key", "Nothing to see here") #=> "Nothing to see here"
Yields a block of destination, yielding each as a string.
(from the destinations example) mail.each_destination { |d| puts "#{d.class}: #{d}" } String: mikel@lindsaar.net String: t@t.com String: bob@me.com
Allows you to loop through each header in the TMail::Mail object in a block Example:
@mail['to'] = 'mikel@elsewhere.org' @mail['from'] = 'me@me.com' @mail.each_header { |k,v| puts "#{k} = #{v}" } # => from = me@me.com # => to = mikel@elsewhere.org
Returns the "friendly" human readable part of the address
Example:
mail = TMail::Mail.new mail.from = "Mikel Lindsaar <mikel@abc.com>" mail.friendly_from #=> "Mikel Lindsaar"
Returns who the email is from as an Array of email address strings instead to an Array of TMail::Address objects which is what Mail#from_addrs returns
Example:
mail = TMail::Mail.new mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.from #=> ["mikel@me.org", "mikel@you.org"]
Destructively sets the "From:" field to the passed array of strings (which should be valid email addresses)
Example:
mail = TMail::Mail.new mail.from = ["mikel@abc.com", "Mikel <mikel@xyz.com>"] mail.from #=> ["mikel@abc.org", "mikel@xyz.org"] mail['from'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
Return a TMail::Addresses instance for each entry in the "From:" field of the mail object header.
If the "From:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.from_addrs #=> nil mail.from_addrs([]) #=> [] mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.from_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively set the to value of the "From:" header to equal the passed in string.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.from_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.from_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Returns the "In-Reply-To:" field contents as an array of this mail instance if it exists
If the in_reply_to field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.in_reply_to #=> nil mail.in_reply_to([]) #=> [] TMail::Mail.load("../test/fixtures/raw_email_reply") mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
Destructively sets the value of the "In-Reply-To:" field of an email.
Accepts an array of a single string of a message id
Example:
mail = TMail::Mail.new mail.in_reply_to = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"] mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
Returns the current main type of the "Content-Type" of the mail instance.
If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.main_type #=> nil mail.main_type([]) #=> [] mail = TMail::Mail.load("../test/fixtures/raw_email") mail.main_type #=> "text"
Returns the message ID for this mail object instance.
If the message_id field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.message_id #=> nil mail.message_id(TMail.new_message_id) #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>" mail.message_id = TMail.new_message_id mail.message_id #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
Destructively sets the message ID of the mail object instance to the passed in string
Invalid message IDs are ignored (silently, unless configured otherwise) and result in a nil message ID. Left and right angle brackets are required.
Example:
mail = TMail::Mail.new mail.message_id = "<348F04F142D69C21-291E56D292BC@xxxx.net>" mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>" mail.message_id = "this_is_my_badly_formatted_message_id" mail.message_id #=> nil
Returns the listed MIME version of this email from the "Mime-Version:" header field
If the mime_version field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.mime_version #=> nil mail.mime_version([]) #=> [] mail = TMail::Mail.load("../test/fixtures/raw_email") mail.mime_version #=> "1.0"
Returns the references of this email (prior messages relating to this message) as an array of message ID strings. Useful when you are trying to thread an email.
If the references field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.references #=> nil mail.references([]) #=> [] mail = TMail::Mail.load("../test/fixtures/raw_email_reply") mail.references #=> ["<473FF3B8.9020707@xxx.org>", "<348F04F142D69C21-291E56D292BC@xxxx.net>"]
Destructively sets the value of the "References:" field of an email.
Accepts an array of strings of message IDs
Example:
mail = TMail::Mail.new mail.references = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"] mail.references #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
Returns an array of reply to addresses that the Mail object has, or if the Mail message has no reply-to, returns an array of the Mail objects from addresses. Else returns the default which can either be passed as a parameter or defaults to nil
Example:
mail.from = "Mikel <mikel@lindsaar.net>" mail.reply_to = nil mail.reply_addresses #=> [""]
Returns who the email is from as an Array of email address strings instead to an Array of TMail::Address objects which is what Mail#reply_to_addrs returns
Example:
mail = TMail::Mail.new mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.reply_to #=> ["mikel@me.org", "mikel@you.org"]
Destructively sets the "Reply-To:" field to the passed array of strings (which should be valid email addresses)
Example:
mail = TMail::Mail.new mail.reply_to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"] mail.reply_to #=> ["mikel@abc.org", "mikel@xyz.org"] mail['reply_to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
Return a TMail::Addresses instance for each entry in the "Reply-To:" field of the mail object header.
If the "Reply-To:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.reply_to_addrs #=> nil mail.reply_to_addrs([]) #=> [] mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively set the to value of the "Reply-To:" header to equal the passed in argument.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.reply_to_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Returns who the sender of this mail is as string instead to an Array of TMail::Address objects which is what Mail#sender_addr returns
Example:
mail = TMail::Mail.new mail.sender = "Mikel <mikel@me.org>" mail.sender #=> "mikel@me.org"
Destructively sets the "Sender:" field to the passed string (which should be a valid email address)
Example:
mail = TMail::Mail.new mail.sender = "mikel@abc.com" mail.sender #=> "mikel@abc.org" mail['sender'].to_s #=> "mikel@abc.com"
Return a TMail::Addresses instance of the "Sender:" field of the mail object header.
If the "Sender:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.sender #=> nil mail.sender([]) #=> [] mail.sender = "Mikel <mikel@me.org>" mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>]
Destructively set the to value of the "Sender:" header to equal the passed in argument.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.sender_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.sender_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively sets the "Content-Type:" header field of this mail object
Allows you to set the main type, sub type as well as parameters to the field. The main type and sub type need to be a string.
The optional params hash can be passed with keys as symbols and values as a string, or strings as keys and values.
Example:
mail = TMail::Mail.new mail.set_content_type("text", "plain") mail.to_s #=> "Content-Type: text/plain\n\n" mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"}) mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n" mail.set_content_type("text", "plain", {"charset" => "EUC-KR", "format" => "flowed"}) mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
Allows you to set the content-disposition of the mail object. Accepts a type and a hash of parameters.
Example:
mail.set_disposition("attachment", {:filename => "test.rb"}) mail.disposition #=> "attachment" mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
Returns the current sub type of the "Content-Type" of the mail instance.
If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.sub_type #=> nil mail.sub_type([]) #=> [] mail = TMail::Mail.load("../test/fixtures/raw_email") mail.sub_type #=> "plain"
Returns the subject of the mail instance.
If the subject field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.
Example:
mail = TMail::Mail.new mail.subject #=> nil mail.subject("") #=> "" mail.subject = "Hello" mail.subject #=> "Hello"
Destructively sets the passed string as the subject of the mail message.
Example
mail = TMail::Mail.new mail.subject #=> "This subject" mail.subject = "Another subject" mail.subject #=> "Another subject"
Returns who the email is to as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns
Example:
mail = TMail::Mail.new mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.to #=> ["mikel@me.org", "mikel@you.org"]
Destructively sets the "To:" field to the passed array of strings (which should be valid email addresses)
Example:
mail = TMail::Mail.new mail.to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"] mail.to #=> ["mikel@abc.org", "mikel@xyz.org"] mail['to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
Return a TMail::Addresses instance for each entry in the "To:" field of the mail object header.
If the "To:" field does not exist, will return nil by default or the value you pass as the optional parameter.
Example:
mail = TMail::Mail.new mail.to_addrs #=> nil mail.to_addrs([]) #=> [] mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Destructively set the to field of the "To:" header to equal the passed in string.
TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.
Example:
mail = TMail::Mail.new mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>" mail.to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
Returns the transfer encoding of the email. Returns nil if no encoding set or returns whatever default you pass as a parameter - note passing the parameter does NOT change the mail object in any way.
Example:
mail = TMail::Mail.load("path_to/base64_encoded_email") mail.transfer_encoding #=> "base64" mail = TMail::Mail.new mail.transfer_encoding #=> nil mail.transfer_encoding("base64") #=> "base64"
Destructively sets the transfer encoding of the mail object to the passed string, you should note though that this does nothing to the mail body, just changes the header value, you will need to encode or decode the body as well to match whatever you put in this header value.
Example:
mail = TMail::Mail.new mail.transfer_encoding #=> nil mail.transfer_encoding = "base64" mail.transfer_encoding #=> "base64"
Returns the named type parameter as a string, from the "Content-Type:" header.
Example:
mail = TMail::Mail.new mail.type_param("charset") #=> nil mail.type_param("charset", []) #=> [] mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"}) mail.type_param("charset") #=> "EUC-KR" mail.type_param("format") #=> "flowed"