Module: Mail

Defined in:: lib/mail.rb,
lib/mail/part.rb,
lib/mail/mail.rb,
lib/mail/body.rb,
lib/mail/field.rb,
lib/mail/header.rb,
lib/mail/fields.rb,
lib/load_parsers.rb,
lib/mail/message.rb,
lib/mail/network.rb,
lib/mail/version.rb,
lib/mail/patterns.rb,
lib/mail/envelope.rb,
lib/mail/elements.rb,
lib/mail/utilities.rb,
lib/mail/multibyte.rb,
lib/mail/encodings.rb,
lib/mail/parts_list.rb,
lib/mail/field_list.rb,
lib/mail/configuration.rb,
lib/mail/encodings/8bit.rb,
lib/mail/encodings/7bit.rb,
lib/mail/multibyte/utils.rb,
lib/mail/parsers/rfc2045.rb,
lib/mail/multibyte/chars.rb,
lib/mail/fields/to_field.rb,
lib/mail/fields/cc_field.rb,
lib/mail/parsers/rfc2822.rb,
lib/mail/elements/address.rb,
lib/mail/parsers/received.rb,
lib/mail/indifferent_hash.rb,
lib/mail/encodings/binary.rb,
lib/mail/attachments_list.rb,
lib/mail/encodings/base64.rb,
lib/mail/fields/bcc_field.rb,
lib/mail/multibyte/unicode.rb,
lib/mail/parsers/date_time.rb,
lib/mail/fields/date_field.rb,
lib/mail/fields/from_field.rb,
lib/mail/fields/sender_field.rb,
lib/mail/parsers/message_ids.rb,
lib/mail/parsers/content_type.rb,
lib/mail/parsers/phrase_lists.rb,
lib/mail/parsers/mime_version.rb,
lib/mail/fields/subject_field.rb,
lib/mail/multibyte/exceptions.rb,
lib/mail/elements/phrase_list.rb,
lib/mail/elements/address_list.rb,
lib/mail/fields/reply_to_field.rb,
lib/mail/parsers/address_lists.rb,
lib/mail/check_delivery_params.rb,
lib/mail/fields/optional_field.rb,
lib/mail/fields/received_field.rb,
lib/mail/parsers/envelope_from.rb,
lib/mail/fields/comments_field.rb,
lib/mail/fields/keywords_field.rb,
lib/mail/fields/resent_to_field.rb,
lib/mail/fields/resent_cc_field.rb,
lib/mail/matchers/has_sent_mail.rb,
lib/mail/fields/structured_field.rb,
lib/mail/fields/content_id_field.rb,
lib/mail/fields/message_id_field.rb,
lib/mail/fields/references_field.rb,
lib/mail/fields/resent_bcc_field.rb,
lib/mail/parsers/content_location.rb,
lib/mail/fields/in_reply_to_field.rb,
lib/mail/fields/return_path_field.rb,
lib/mail/fields/resent_from_field.rb,
lib/mail/fields/resent_date_field.rb,
lib/mail/parsers/rfc2822_obsolete.rb,
lib/mail/fields/mime_version_field.rb,
lib/mail/fields/common/common_date.rb,
lib/mail/version_specific/ruby_1_9.rb,
lib/mail/version_specific/ruby_1_8.rb,
lib/mail/fields/unstructured_field.rb,
lib/mail/elements/received_element.rb,
lib/mail/fields/content_type_field.rb,
lib/mail/encodings/quoted_printable.rb,
lib/mail/elements/date_time_element.rb,
lib/mail/fields/common/common_field.rb,
lib/mail/fields/resent_sender_field.rb,
lib/mail/parsers/content_disposition.rb,
lib/mail/encodings/transfer_encoding.rb,
lib/mail/elements/message_ids_element.rb,
lib/mail/fields/common/parameter_hash.rb,
lib/mail/fields/common/common_address.rb,
lib/mail/elements/content_type_element.rb,
lib/mail/network/delivery_methods/smtp.rb,
lib/mail/network/delivery_methods/exim.rb,
lib/mail/fields/content_location_field.rb,
lib/mail/elements/mime_version_element.rb,
lib/mail/network/retriever_methods/base.rb,
lib/mail/elements/envelope_from_element.rb,
lib/mail/network/retriever_methods/imap.rb,
lib/mail/fields/resent_message_id_field.rb,
lib/mail/network/retriever_methods/pop3.rb,
lib/mail/fields/common/common_message_id.rb,
lib/mail/fields/common/address_container.rb,
lib/mail/fields/content_description_field.rb,
lib/mail/fields/content_disposition_field.rb,
lib/mail/network/delivery_methods/sendmail.rb,
lib/mail/elements/content_location_element.rb,
lib/mail/parsers/content_transfer_encoding.rb,
lib/mail/network/delivery_methods/test_mailer.rb,
lib/mail/elements/content_disposition_element.rb,
lib/mail/network/delivery_methods/file_delivery.rb,
lib/mail/fields/content_transfer_encoding_field.rb,
lib/mail/network/delivery_methods/smtp_connection.rb,
lib/mail/network/retriever_methods/test_retriever.rb,
lib/mail/elements/content_transfer_encoding_element.rb

Defined Under Namespace

Modules: AddressLists, CheckDeliveryParams, CommonAddress, CommonDate, CommonField, CommonMessageId, ContentDisposition, ContentLocation, ContentTransferEncoding, ContentType, DateTime, Encodings, EnvelopeFrom, Matchers, MessageIds, MimeVersion, Multibyte, Patterns, PhraseLists, RFC2045, RFC2822, RFC2822Obsolete, Received, Utilities, VERSION Classes: Address, AddressContainer, AddressList, AddressListsParser, AttachmentsList, BccField, Body, CcField, CommentsField, Configuration, ContentDescriptionField, ContentDispositionElement, ContentDispositionField, ContentDispositionParser, ContentIdField, ContentLocationElement, ContentLocationField, ContentLocationParser, ContentTransferEncodingElement, ContentTransferEncodingField, ContentTransferEncodingParser, ContentTypeElement, ContentTypeField, ContentTypeParser, DateField, DateTimeElement, DateTimeParser, Envelope, EnvelopeFromElement, EnvelopeFromParser, Exim, Field, FieldList, FileDelivery, FromField, Header, IMAP, InReplyToField, IndifferentHash, KeywordsField, Message, MessageIdField, MessageIdsElement, MessageIdsParser, MimeVersionElement, MimeVersionField, MimeVersionParser, OptionalField, POP3, ParameterHash, Part, PartsList, PhraseList, PhraseListsParser, RFC2045Parser, RFC2822ObsoleteParser, RFC2822Parser, ReceivedElement, ReceivedField, ReceivedParser, ReferencesField, ReplyToField, ResentBccField, ResentCcField, ResentDateField, ResentFromField, ResentMessageIdField, ResentSenderField, ResentToField, Retriever, ReturnPathField, Ruby18, Ruby19, SMTP, SMTPConnection, SenderField, Sendmail, StructuredField, SubjectField, TestMailer, TestRetriever, ToField, UnknownEncodingType, UnstructuredField

Constant Summary

RubyVer =

Ruby18

@@autoloads =

{}

@@delivery_notification_observers = Initialize the observers and interceptors arrays

[]

@@delivery_interceptors =

[]

Class Method Summary (collapse)

+ (Object) all(*args, &block)

Receive all emails from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) compile_parser(parser)
+ (Object) connection(&block)
+ (Object) defaults(&block)

Sets the default delivery method and retriever method for all new Mail objects.
+ (Object) delete_all(*args, &block)

Delete all emails from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) deliver(*args, &block)

Send an email using the default configuration.
+ (Object) delivery_method

Returns the delivery method selected, defaults to an instance of Mail::SMTP.
+ (Object) eager_autoload!

This runs through the autoload list and explictly requires them for you.
+ (Object) find(*args, &block)

Find emails from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) find_and_delete(*args, &block)

Finds and then deletes retrieved emails from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) first(*args, &block)

Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) inform_interceptors(mail)
+ (Object) inform_observers(mail)
+ (Object) last(*args, &block)

Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.
+ (Object) new(*args, &block)

Allows you to create a new Mail::Message object.
+ (Object) read(filename)

Reads in an email message from a path and instantiates it as a new Mail::Message.
+ (Object) read_from_string(mail_as_string)

Instantiates a new Mail::Message using a string.
+ (Object) register_autoload(name, path)
+ (Object) register_interceptor(interceptor)

You can register an object to be given every mail object that will be sent, before it is sent.
+ (Object) register_observer(observer)

You can register an object to be informed of every email that is sent through this method.
+ (Object) retriever_method

Returns the retriever method selected, defaults to an instance of Mail::POP3.

Class Method Details

+ (`Object`) all(*args, &block)

Receive all emails from the default retriever See Mail::Retriever for a complete documentation.



170
171
172

# File 'lib/mail/mail.rb', line 170

def self.all(*args, &block)
  retriever_method.all(*args, &block)
end

+ (`Object`) compile_parser(parser)

# File 'lib/load_parsers.rb', line 9

def self.compile_parser(parser)
  require 'treetop/compiler'
  Treetop.load(File.join(File.dirname(__FILE__)) + "/mail/parsers/#{parser}")
end

+ (`Object`) connection(&block)



190
191
192

# File 'lib/mail/mail.rb', line 190

def Mail.connection(&block)
  retriever_method.connection(&block)
end

+ (`Object`) defaults(&block)

Sets the default delivery method and retriever method for all new Mail objects. The delivery_method and retriever_method default to :smtp and :pop3, with defaults set.

So sending a new email, if you have an SMTP server running on localhost is as easy as:

Mail.deliver do
  to      'mikel@test.lindsaar.net'
  from    'bob@test.lindsaar.net'
  subject 'hi there!'
  body    'this is a body'
end

If you do not specify anything, you will get the following equivalent code set in every new mail object:

Mail.defaults do
  delivery_method :smtp, { :address              => "localhost",
                           :port                 => 25,
                           :domain               => 'localhost.localdomain',
                           :user_name            => nil,
                           :password             => nil,
                           :authentication       => nil,
                           :enable_starttls_auto => true  }

  retriever_method :pop3, { :address             => "localhost",
                            :port                => 995,
                            :user_name           => nil,
                            :password            => nil,
                            :enable_ssl          => true }
end

Mail.delivery_method.new  #=> Mail::SMTP instance
Mail.retriever_method.new #=> Mail::POP3 instance

Each mail object inherits the default set in Mail.delivery_method, however, on a per email basis, you can override the method:

mail.delivery_method :sendmail

Or you can override the method and pass in settings:

mail.delivery_method :sendmail, { :address => 'some.host' }

You can also just modify the settings:

mail.delivery_settings = { :address => 'some.host' }

The passed in hash is just merged against the defaults with merge! and the result assigned the mail object. So the above example will change only the :address value of the global smtp_settings to be 'some.host', keeping all other values



105
106
107

# File 'lib/mail/mail.rb', line 105

def self.defaults(&block)
  Configuration.instance.instance_eval(&block)
end

+ (`Object`) delete_all(*args, &block)

Delete all emails from the default retriever See Mail::Retriever for a complete documentation.



181
182
183

# File 'lib/mail/mail.rb', line 181

def self.delete_all(*args, &block)
  retriever_method.delete_all(*args, &block)
end

+ (`Object`) deliver(*args, &block)

Send an email using the default configuration. You do need to set a default configuration first before you use self.deliver, if you don't, an appropriate error will be raised telling you to.

If you do not specify a delivery type, SMTP will be used.

Mail.deliver do
 to 'mikel@test.lindsaar.net'
 from 'ada@test.lindsaar.net'
 subject 'This is a test email'
 body 'Not much to say here'
end

You can also do:

mail = Mail.read('email.eml')
mail.deliver!

And your email object will be created and sent.

# File 'lib/mail/mail.rb', line 138

def self.deliver(*args, &block)
  mail = self.new(args, &block)
  mail.deliver
  mail
end

+ (`Object`) delivery_method

Returns the delivery method selected, defaults to an instance of Mail::SMTP



110
111
112

# File 'lib/mail/mail.rb', line 110

def self.delivery_method
  Configuration.instance.delivery_method
end

+ (`Object`) eager_autoload!

This runs through the autoload list and explictly requires them for you. Useful when running mail in a threaded process.

Usage:

require 'mail'
Mail.eager_autoload!



61
62
63

# File 'lib/mail.rb', line 61

def self.eager_autoload!
  @@autoloads.each { |_,path| require(path) }
end

+ (`Object`) find(*args, &block)

Find emails from the default retriever See Mail::Retriever for a complete documentation.



146
147
148

# File 'lib/mail/mail.rb', line 146

def self.find(*args, &block)
  retriever_method.find(*args, &block)
end

+ (`Object`) find_and_delete(*args, &block)

Finds and then deletes retrieved emails from the default retriever See Mail::Retriever for a complete documentation.



152
153
154

# File 'lib/mail/mail.rb', line 152

def self.find_and_delete(*args, &block)
  retriever_method.find_and_delete(*args, &block)
end

+ (`Object`) first(*args, &block)

Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.



158
159
160

# File 'lib/mail/mail.rb', line 158

def self.first(*args, &block)
  retriever_method.first(*args, &block)
end

+ (`Object`) inform_interceptors(mail)

# File 'lib/mail/mail.rb', line 228

def self.inform_interceptors(mail)
  @@delivery_interceptors.each do |interceptor|
    interceptor.delivering_email(mail)
  end
end

+ (`Object`) inform_observers(mail)

# File 'lib/mail/mail.rb', line 222

def self.inform_observers(mail)
  @@delivery_notification_observers.each do |observer|
    observer.delivered_email(mail)
  end
end

+ (`Object`) last(*args, &block)

Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.



164
165
166

# File 'lib/mail/mail.rb', line 164

def self.last(*args, &block)
  retriever_method.last(*args, &block)
end

+ (`Object`) new(*args, &block)

Allows you to create a new Mail::Message object.

You can make an email via passing a string or passing a block.

For example, the following two examples will create the same email message:

Creating via a string:

string = "To: mikel@test.lindsaar.net\r\n"
string << "From: bob@test.lindsaar.net\r\n"
string << "Subject: This is an email\r\n"
string << "\r\n"
string << "This is the body"
Mail.new(string)

Or creating via a block:

message = Mail.new do
  to 'mikel@test.lindsaar.net'
  from 'bob@test.lindsaar.net'
  subject 'This is an email'
  body 'This is the body'
end

Or creating via a hash (or hash like object):

message = Mail.new({:to => 'mikel@test.lindsaar.net',
                    'from' => 'bob@test.lindsaar.net',
                    :subject => 'This is an email',
                    :body => 'This is the body' })

Note, the hash keys can be strings or symbols, the passed in object does not need to be a hash, it just needs to respond to :each_pair and yield each key value pair.

As a side note, you can also create a new email through creating a Mail::Message object directly and then passing in values via string, symbol or direct method calls. See Mail::Message for more information.

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



49
50
51

# File 'lib/mail/mail.rb', line 49

def self.new(*args, &block)
  Message.new(args, &block)
end

+ (`Object`) read(filename)

Reads in an email message from a path and instantiates it as a new Mail::Message



175
176
177

# File 'lib/mail/mail.rb', line 175

def self.read(filename)
  self.new(File.open(filename, 'rb') { |f| f.read })
end

+ (`Object`) read_from_string(mail_as_string)

Instantiates a new Mail::Message using a string



186
187
188

# File 'lib/mail/mail.rb', line 186

def Mail.read_from_string(mail_as_string)
  Mail.new(mail_as_string)
end

+ (`Object`) register_autoload(name, path)

# File 'lib/mail.rb', line 49

def self.register_autoload(name, path)
  @@autoloads[name] = path
  autoload(name, path)
end

+ (`Object`) register_interceptor(interceptor)

You can register an object to be given every mail object that will be sent, before it is sent. So if you want to add special headers or modify any email that gets sent through the Mail library, you can do so.

Your object needs to respond to a single method #delivering_email(mail) which receives the email that is about to be sent. Make your modifications directly to this object.

# File 'lib/mail/mail.rb', line 216

def self.register_interceptor(interceptor)
  unless @@delivery_interceptors.include?(interceptor)
    @@delivery_interceptors << interceptor
  end
end

+ (`Object`) register_observer(observer)

You can register an object to be informed of every email that is sent through this method.

Your object needs to respond to a single method #delivered_email(mail) which receives the email that is sent.

# File 'lib/mail/mail.rb', line 203

def self.register_observer(observer)
  unless @@delivery_notification_observers.include?(observer)
    @@delivery_notification_observers << observer
  end
end

+ (`Object`) retriever_method

Returns the retriever method selected, defaults to an instance of Mail::POP3



115
116
117

# File 'lib/mail/mail.rb', line 115

def self.retriever_method
  Configuration.instance.retriever_method
end

Module: Mail

Defined Under Namespace

Constant Summary

Class Method Summary (collapse)

Class Method Details

+ (Object) all(*args, &block)

+ (Object) compile_parser(parser)

+ (Object) connection(&block)

+ (Object) defaults(&block)

+ (Object) delete_all(*args, &block)

+ (Object) deliver(*args, &block)

+ (Object) delivery_method

+ (Object) eager_autoload!

+ (Object) find(*args, &block)

+ (Object) find_and_delete(*args, &block)

+ (Object) first(*args, &block)

+ (Object) inform_interceptors(mail)

+ (Object) inform_observers(mail)

+ (Object) last(*args, &block)

+ (Object) new(*args, &block)

+ (Object) read(filename)

+ (Object) read_from_string(mail_as_string)

+ (Object) register_autoload(name, path)

+ (Object) register_interceptor(interceptor)

+ (Object) register_observer(observer)

+ (Object) retriever_method