# module 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 Mail::Envelope#from and Mail::Envelope#date for your use.

encoding: utf-8

# Comments Field¶ ↑

The Comments field inherits from UnstructuredField and handles the Comments: header field in the email.

Sending comments to a mail message will instantiate a Mail::Field object that has a CommentsField as its field type.

An email header can have as many comments fields as it wants. There is no upper limit, the comments field is also optional (that is, no comment is needed)

## Examples:¶ ↑

    mail = Mail.new
    mail.comments = 'This is a comment'
    mail.comments    #=> 'This is a comment'
    mail[:comments]  #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4
    mail['comments'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4
    mail['comments'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4

    mail.comments = "This is another comment"
    mail[:comments].map { |c| c.to_s }
    #=> ['This is a comment', "This is another comment"]

keywords = “Keywords:” phrase *(“,” phrase) CRLF

trace = [return]

    1*received

return = “Return-Path:” path CRLF

path = ([CFWS] “<” ([CFWS] / addr-spec) “>” [CFWS]) /

    obs-path

received = “Received:” name-val-list “;” date-time CRLF

name-val-list = [CFWS] [name-val-pair *(CFWS name-val-pair)]

name-val-pair = item-name CFWS item-value

item-name = ALPHA *([“-”] (ALPHA / DIGIT))

item-value = 1*angle-addr / addr-spec /

    atom / domain / msg-id

subject = “Subject:” unstructured CRLF

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

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/address_lists_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_disposition_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_location_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_transfer_encoding_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_type_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/date_time_machine.rb.rl”

line 10 “/Users/raindrift/workspace/mail/lib/mail/parsers/ragel/ruby/machines/envelope_from_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/message_ids_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/mime_version_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/phrase_lists_machine.rb.rl”

line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/received_machine.rb.rl”

### Constants

RANDOM_TAG
RubyVer

### 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 169
    def self.all(*args, &block)
      retriever_method.all(*args, &block)
    end

connection(&block) click to toggle source

    # File lib/mail/mail.rb, line 189
    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 ::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

    # File lib/mail/mail.rb, line 104
    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 180
    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 137
    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 109
    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 64
    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 145
    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 151
    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 157
    def self.first(*args, &block)
      retriever_method.first(*args, &block)
    end

inform_interceptors(mail) click to toggle source

    # File lib/mail/mail.rb, line 239
    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 233
    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 163
    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 48
    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 174
    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 185
    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 52
    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 221
    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 202
    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 114
    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 229
    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 210
    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 249
    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 258
    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 262
    def self.uniq
      @@uniq += 1
    end