Module: Mail

Defined in:
lib/mail.rb,
lib/mail/body.rb,
lib/mail/mail.rb,
lib/mail/part.rb,
lib/mail/yaml.rb,
lib/mail/field.rb,
lib/mail/fields.rb,
lib/mail/header.rb,
lib/mail/message.rb,
lib/mail/network.rb,
lib/mail/version.rb,
lib/mail/elements.rb,
lib/mail/envelope.rb,
lib/mail/constants.rb,
lib/mail/encodings.rb,
lib/mail/multibyte.rb,
lib/mail/utilities.rb,
lib/mail/field_list.rb,
lib/mail/parts_list.rb,
lib/mail/parser_tools.rb,
lib/mail/configuration.rb,
lib/mail/smtp_envelope.rb,
lib/mail/encodings/7bit.rb,
lib/mail/encodings/8bit.rb,
lib/mail/fields/cc_field.rb,
lib/mail/fields/to_field.rb,
lib/mail/multibyte/chars.rb,
lib/mail/multibyte/utils.rb,
lib/mail/attachments_list.rb,
lib/mail/elements/address.rb,
lib/mail/encodings/base64.rb,
lib/mail/encodings/binary.rb,
lib/mail/fields/bcc_field.rb,
lib/mail/indifferent_hash.rb,
lib/mail/fields/date_field.rb,
lib/mail/fields/from_field.rb,
lib/mail/multibyte/unicode.rb,
lib/mail/encodings/identity.rb,
lib/mail/fields/common_field.rb,
lib/mail/fields/sender_field.rb,
lib/mail/elements/phrase_list.rb,
lib/mail/fields/subject_field.rb,
lib/mail/check_delivery_params.rb,
lib/mail/elements/address_list.rb,
lib/mail/fields/comments_field.rb,
lib/mail/fields/keywords_field.rb,
lib/mail/fields/optional_field.rb,
lib/mail/fields/parameter_hash.rb,
lib/mail/fields/received_field.rb,
lib/mail/fields/reply_to_field.rb,
lib/mail/encodings/unix_to_unix.rb,
lib/mail/fields/resent_cc_field.rb,
lib/mail/fields/resent_to_field.rb,
lib/mail/matchers/has_sent_mail.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/fields/structured_field.rb,
lib/mail/fields/common_date_field.rb,
lib/mail/fields/in_reply_to_field.rb,
lib/mail/fields/resent_date_field.rb,
lib/mail/fields/resent_from_field.rb,
lib/mail/fields/return_path_field.rb,
lib/mail/elements/received_element.rb,
lib/mail/fields/content_type_field.rb,
lib/mail/fields/mime_version_field.rb,
lib/mail/fields/unstructured_field.rb,
lib/mail/elements/date_time_element.rb,
lib/mail/encodings/quoted_printable.rb,
lib/mail/fields/resent_sender_field.rb,
lib/mail/encodings/transfer_encoding.rb,
lib/mail/fields/common_address_field.rb,
lib/mail/elements/message_ids_element.rb,
lib/mail/matchers/attachment_matchers.rb,
lib/mail/elements/content_type_element.rb,
lib/mail/elements/mime_version_element.rb,
lib/mail/fields/content_location_field.rb,
lib/mail/fields/named_structured_field.rb,
lib/mail/network/delivery_methods/exim.rb,
lib/mail/network/delivery_methods/smtp.rb,
lib/mail/elements/envelope_from_element.rb,
lib/mail/fields/common_message_id_field.rb,
lib/mail/fields/resent_message_id_field.rb,
lib/mail/network/retriever_methods/base.rb,
lib/mail/network/retriever_methods/imap.rb,
lib/mail/network/retriever_methods/pop3.rb,
lib/mail/fields/named_unstructured_field.rb,
lib/mail/fields/content_description_field.rb,
lib/mail/fields/content_disposition_field.rb,
lib/mail/elements/content_location_element.rb,
lib/mail/network/delivery_methods/sendmail.rb,
lib/mail/elements/content_disposition_element.rb,
lib/mail/network/delivery_methods/test_mailer.rb,
lib/mail/fields/content_transfer_encoding_field.rb,
lib/mail/network/delivery_methods/file_delivery.rb,
lib/mail/network/delivery_methods/logger_delivery.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

Overview

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

Defined Under Namespace

Modules: CheckDeliveryParams, Constants, Encodings, Matchers, Multibyte, ParserTools, Utilities, VERSION, YAML Classes: Address, AddressContainer, AddressList, AttachmentsList, BccField, Body, CcField, CommentsField, CommonAddressField, CommonDateField, CommonField, CommonMessageIdField, Configuration, ContentDescriptionField, ContentDispositionElement, ContentDispositionField, ContentIdField, ContentLocationElement, ContentLocationField, ContentTransferEncodingElement, ContentTransferEncodingField, ContentTypeElement, ContentTypeField, DateField, DateTimeElement, Envelope, EnvelopeFromElement, Exim, Field, FieldList, FileDelivery, FromField, Header, IMAP, InReplyToField, IndifferentHash, KeywordsField, LoggerDelivery, Message, MessageIdField, MessageIdsElement, MimeVersionElement, MimeVersionField, NamedStructuredField, NamedUnstructuredField, OptionalField, POP3, ParameterHash, Part, PartsList, PhraseList, ReceivedElement, ReceivedField, ReferencesField, ReplyToField, ResentBccField, ResentCcField, ResentDateField, ResentFromField, ResentMessageIdField, ResentSenderField, ResentToField, Retriever, ReturnPathField, SMTP, SMTPConnection, SenderField, Sendmail, SmtpEnvelope, StructuredField, SubjectField, TestMailer, TestRetriever, ToField, UnknownEncodingType, UnstructuredField

Constant Summary collapse

@@autoloads = 
{}
@@delivery_notification_observers =

Initialize the observers and interceptors arrays

[]
@@delivery_interceptors = 
[]

Class Method Summary collapse

Class Method Details

.all(*args, &block) ⇒ Object

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



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

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

.connection(&block) ⇒ Object 



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

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

.defaults(&block) ⇒ Object

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      '[email protected]'
  from    '[email protected]'
  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'



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

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

.delete_all(*args, &block) ⇒ Object

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



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

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

.deliver(*args, &block) ⇒ Object

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 '[email protected]'
 from '[email protected]'
 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.



131
132
133
134
135
 
# File 'lib/mail/mail.rb', line 131

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

.delivery_method ⇒ Object

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



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

def self.delivery_method
  Configuration.instance.delivery_method
end

.eager_autoload! ⇒ Object

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!



35
36
37
 
# File 'lib/mail.rb', line 35

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

.find(*args, &block) ⇒ Object

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



139
140
141
 
# File 'lib/mail/mail.rb', line 139

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

.find_and_delete(*args, &block) ⇒ Object

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



145
146
147
 
# 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) ⇒ Object

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



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

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

.inform_interceptors(mail) ⇒ Object 



233
234
235
236
237
 
# 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) ⇒ Object 



227
228
229
230
231
 
# 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) ⇒ Object

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



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

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

.new(*args, &block) ⇒ Object

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: [email protected]\r\n"
string << "From: [email protected]\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 '[email protected]'
  from '[email protected]'
  subject 'This is an email'
  body 'This is the body'
end

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

message = Mail.new({:to => '[email protected]',
                    'from' => '[email protected]',
                    :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 = '[email protected]'
mail[:from] = '[email protected]'
mail['subject'] = 'This is an email'
mail.body = 'This is the body'



50
51
52
 
# File 'lib/mail/mail.rb', line 50

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

.read(filename) ⇒ Object

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



168
169
170
 
# 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) ⇒ Object

Instantiates a new Mail::Message using a string



179
180
181
 
# 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) ⇒ Object 



23
24
25
26
 
# File 'lib/mail.rb', line 23

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

.register_interceptor(interceptor) ⇒ Object

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.



215
216
217
218
219
 
# 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) ⇒ Object

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.



196
197
198
199
200
 
# 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 ⇒ Object

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



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

def self.retriever_method
  Configuration.instance.retriever_method
end

.unregister_interceptor(interceptor) ⇒ Object

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



223
224
225
 
# File 'lib/mail/mail.rb', line 223

def self.unregister_interceptor(interceptor)
  @@delivery_interceptors.delete(interceptor)
end

.unregister_observer(observer) ⇒ Object

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



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

def self.unregister_observer(observer)
  @@delivery_notification_observers.delete(observer)
end