module Mail

This whole class and associated specs is deprecated and will go away in the version 3 release of mail.

Mail Envelope

The Envelope class provides a field for the first line in an mbox file, that looks like “From mikel@test.lindsaar.net DATETIME”

This envelope class reads that line, and turns it into an Envelope.from and Envelope.date for your use.

encoding: utf-8

This is an almost cut and paste from ActiveSupport v3.0.6, copied in here so that Mail itself does not depend on ActiveSupport to avoid versioning conflicts

Constants

RANDOM_TAG

Public Class Methods

all(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 163
def self.all(*args, &block)
  retriever_method.all(*args, &block)
end
connection(&block) click to toggle source
# File lib/mail/mail.rb, line 183
def Mail.connection(&block)
  retriever_method.connection(&block)
end
defaults(&block) click to toggle source

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 :smtp

Or you can override the method and pass in settings:

mail.delivery_method :smtp, :address => 'some.host'
# File lib/mail/mail.rb, line 98
def self.defaults(&block)
  Configuration.instance.instance_eval(&block)
end
delete_all(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 174
def self.delete_all(*args, &block)
  retriever_method.delete_all(*args, &block)
end
deliver(*args, &block) click to toggle source

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 131
def self.deliver(*args, &block)
  mail = self.new(args, &block)
  mail.deliver
  mail
end
delivery_method() click to toggle source

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

# File lib/mail/mail.rb, line 103
def self.delivery_method
  Configuration.instance.delivery_method
end
eager_autoload!() click to toggle source

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!
# File lib/mail.rb, line 35
def self.eager_autoload!
  @@autoloads.each { |_,path| require(path) }
end
find(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 139
def self.find(*args, &block)
  retriever_method.find(*args, &block)
end
find_and_delete(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 145
def self.find_and_delete(*args, &block)
  retriever_method.find_and_delete(*args, &block)
end
first(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 151
def self.first(*args, &block)
  retriever_method.first(*args, &block)
end
inform_interceptors(mail) click to toggle source
# File lib/mail/mail.rb, line 233
def self.inform_interceptors(mail)
  @@delivery_interceptors.each do |interceptor|
    interceptor.delivering_email(mail)
  end
end
inform_observers(mail) click to toggle source
# File lib/mail/mail.rb, line 227
def self.inform_observers(mail)
  @@delivery_notification_observers.each do |observer|
    observer.delivered_email(mail)
  end
end
last(*args, &block) click to toggle source

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

# File lib/mail/mail.rb, line 157
def self.last(*args, &block)
  retriever_method.last(*args, &block)
end
new(*args, &block) click to toggle source

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'
# File lib/mail/mail.rb, line 50
def self.new(*args, &block)
  Message.new(args, &block)
end
read(filename) click to toggle source

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

# File lib/mail/mail.rb, line 168
def self.read(filename)
  self.new(File.open(filename, 'rb') { |f| f.read })
end
read_from_string(mail_as_string) click to toggle source

Instantiates a new Mail::Message using a string

# File lib/mail/mail.rb, line 179
def Mail.read_from_string(mail_as_string)
  Mail.new(mail_as_string)
end
register_autoload(name, path) click to toggle source
# File lib/mail.rb, line 23
def self.register_autoload(name, path)
  @@autoloads[name] = path
  autoload(name, path)
end
register_interceptor(interceptor) click to toggle source

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 215
def self.register_interceptor(interceptor)
  unless @@delivery_interceptors.include?(interceptor)
    @@delivery_interceptors << interceptor
  end
end
register_observer(observer) click to toggle source

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 196
def self.register_observer(observer)
  unless @@delivery_notification_observers.include?(observer)
    @@delivery_notification_observers << observer
  end
end
retriever_method() click to toggle source

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

# File lib/mail/mail.rb, line 108
def self.retriever_method
  Configuration.instance.retriever_method
end
unregister_interceptor(interceptor) click to toggle source

Unregister the given interceptor, allowing mail to resume operations without it.

# File lib/mail/mail.rb, line 223
def self.unregister_interceptor(interceptor)
  @@delivery_interceptors.delete(interceptor)
end
unregister_observer(observer) click to toggle source

Unregister the given observer, allowing mail to resume operations without it.

# File lib/mail/mail.rb, line 204
def self.unregister_observer(observer)
  @@delivery_notification_observers.delete(observer)
end

Protected Class Methods

random_tag() click to toggle source
# File lib/mail/mail.rb, line 243
def self.random_tag
  t = Time.now
  sprintf(RANDOM_TAG,
          t.to_i, t.tv_usec,
          $$, Thread.current.object_id.abs, self.uniq, rand(255))
end

Private Class Methods

something_random() click to toggle source
# File lib/mail/mail.rb, line 252
def self.something_random
  (Thread.current.object_id * rand(255) / Time.now.to_f).to_s.slice(-3..-1).to_i
end
uniq() click to toggle source
# File lib/mail/mail.rb, line 256
def self.uniq
  @@uniq += 1
end

Public Instance Methods

delete_attachments() click to toggle source
# File lib/mail/parts_list.rb, line 98
def delete_attachments
  recursive_delete_if { |part|
    part.attachment?
  }
end
sort() click to toggle source
# File lib/mail/parts_list.rb, line 104
def sort
  self.class.new(@parts.sort)
end
sort!(order) click to toggle source
# File lib/mail/parts_list.rb, line 108
def sort!(order)
  # stable sort should be used to maintain the relative order as the parts are added
  i = 0;
  sorted = @parts.sort_by do |a|
    # OK, 10000 is arbitrary... if anyone actually wants to explicitly sort 10000 parts of a
    # single email message... please show me a use case and I'll put more work into this method,
    # in the meantime, it works :)
    get_order_value(a, order) << (i += 1)
  end
  @parts.clear
  sorted.each { |p| @parts << p }
end

Private Instance Methods

get_order_value(part, order) click to toggle source
# File lib/mail/parts_list.rb, line 123
def get_order_value(part, order)
  is_attachment = part.respond_to?(:attachment?) && part.attachment?
  has_content_type = part.respond_to?(:content_type) && !part[:content_type].nil?

  [is_attachment ? 1 : 0, (has_content_type ? order.index(part[:content_type].string.downcase) : nil) || 10000]
end