Module: Mail
- Defined in:
- lib/mail.rb,
lib/mail/body.rb,
lib/mail/mail.rb,
lib/mail/part.rb,
lib/mail/field.rb,
lib/mail/fields.rb,
lib/mail/header.rb,
lib/mail/message.rb,
lib/mail/network.rb,
lib/mail/parsers.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/configuration.rb,
lib/mail/parsers/ragel.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/parsers/ragel/ruby.rb,
lib/mail/fields/sender_field.rb,
lib/mail/elements/phrase_list.rb,
lib/mail/fields/subject_field.rb,
lib/mail/multibyte/exceptions.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/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/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/common/common_date.rb,
lib/mail/fields/content_type_field.rb,
lib/mail/fields/mime_version_field.rb,
lib/mail/fields/unstructured_field.rb,
lib/mail/parsers/ragel/parser_info.rb,
lib/mail/version_specific/ruby_1_8.rb,
lib/mail/version_specific/ruby_1_9.rb,
lib/mail/elements/date_time_element.rb,
lib/mail/encodings/quoted_printable.rb,
lib/mail/fields/common/common_field.rb,
lib/mail/fields/resent_sender_field.rb,
lib/mail/encodings/transfer_encoding.rb,
lib/mail/elements/message_ids_element.rb,
lib/mail/fields/common/common_address.rb,
lib/mail/fields/common/parameter_hash.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/network/delivery_methods/exim.rb,
lib/mail/network/delivery_methods/smtp.rb,
lib/mail/elements/envelope_from_element.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/common/address_container.rb,
lib/mail/fields/common/common_message_id.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/smtp_connection.rb,
lib/mail/network/retriever_methods/test_retriever.rb,
lib/mail/elements/content_transfer_encoding_element.rb,
lib/mail/parsers/ragel/ruby/machines/received_machine.rb,
lib/mail/parsers/ragel/ruby/machines/date_time_machine.rb,
lib/mail/parsers/ragel/ruby/machines/message_ids_machine.rb,
lib/mail/parsers/ragel/ruby/machines/content_type_machine.rb,
lib/mail/parsers/ragel/ruby/machines/mime_version_machine.rb,
lib/mail/parsers/ragel/ruby/machines/phrase_lists_machine.rb,
lib/mail/parsers/ragel/ruby/machines/address_lists_machine.rb,
lib/mail/parsers/ragel/ruby/machines/envelope_from_machine.rb,
lib/mail/parsers/ragel/ruby/machines/content_location_machine.rb,
lib/mail/parsers/ragel/ruby/machines/content_disposition_machine.rb,
lib/mail/parsers/ragel/ruby/machines/content_transfer_encoding_machine.rb
Defined Under Namespace
Modules: CheckDeliveryParams, CommonAddress, CommonDate, CommonField, CommonMessageId, Constants, Encodings, Matchers, Multibyte, Parsers, Utilities, VERSION Classes: Address, AddressContainer, AddressList, AttachmentsList, BccField, Body, CcField, CommentsField, 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, Message, MessageIdField, MessageIdsElement, MimeVersionElement, MimeVersionField, OptionalField, POP3, ParameterHash, Part, PartsList, PhraseList, ReceivedElement, ReceivedField, 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 collapse
- RubyVer =
Ruby18
- @@autoloads =
{}
- @@delivery_notification_observers =
Initialize the observers and interceptors arrays
[]
- @@delivery_interceptors =
[]
Class Method Summary collapse
-
.all(*args, &block) ⇒ Object
Receive all emails from the default retriever See Mail::Retriever for a complete documentation.
- .connection(&block) ⇒ Object
-
.defaults(&block) ⇒ Object
Sets the default delivery method and retriever method for all new Mail objects.
-
.delete_all(*args, &block) ⇒ Object
Delete all emails from the default retriever See Mail::Retriever for a complete documentation.
-
.deliver(*args, &block) ⇒ Object
Send an email using the default configuration.
-
.delivery_method ⇒ Object
Returns the delivery method selected, defaults to an instance of Mail::SMTP.
-
.eager_autoload! ⇒ Object
This runs through the autoload list and explictly requires them for you.
-
.find(*args, &block) ⇒ Object
Find emails from the default retriever See Mail::Retriever for a complete documentation.
-
.find_and_delete(*args, &block) ⇒ Object
Finds and then deletes retrieved emails from the default retriever See Mail::Retriever for a complete documentation.
-
.first(*args, &block) ⇒ Object
Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.
- .inform_interceptors(mail) ⇒ Object
- .inform_observers(mail) ⇒ Object
-
.last(*args, &block) ⇒ Object
Receive the first email(s) from the default retriever See Mail::Retriever for a complete documentation.
-
.new(*args, &block) ⇒ Object
Allows you to create a new Mail::Message object.
-
.read(filename) ⇒ Object
Reads in an email message from a path and instantiates it as a new Mail::Message.
-
.read_from_string(mail_as_string) ⇒ Object
Instantiates a new Mail::Message using a string.
- .register_autoload(name, path) ⇒ Object
-
.register_interceptor(interceptor) ⇒ Object
You can register an object to be given every mail object that will be sent, before it is sent.
-
.register_observer(observer) ⇒ Object
You can register an object to be informed of every email that is sent through this method.
-
.retriever_method ⇒ Object
Returns the retriever method selected, defaults to an instance of Mail::POP3.
-
.unregister_interceptor(interceptor) ⇒ Object
Unregister the given interceptor, allowing mail to resume operations without it.
-
.unregister_observer(observer) ⇒ Object
Unregister the given observer, allowing mail to resume operations without it.
Class Method Details
.all(*args, &block) ⇒ Object
Receive all emails from the default retriever See Mail::Retriever for a complete documentation.
171 172 173 |
# File 'lib/mail/mail.rb', line 171 def self.all(*args, &block) retriever_method.all(*args, &block) end |
.connection(&block) ⇒ Object
191 192 193 |
# File 'lib/mail/mail.rb', line 191 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 :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
106 107 108 |
# File 'lib/mail/mail.rb', line 106 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.
182 183 184 |
# File 'lib/mail/mail.rb', line 182 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.
139 140 141 142 143 |
# File 'lib/mail/mail.rb', line 139 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
111 112 113 |
# File 'lib/mail/mail.rb', line 111 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!
66 67 68 |
# File 'lib/mail.rb', line 66 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.
147 148 149 |
# File 'lib/mail/mail.rb', line 147 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.
153 154 155 |
# File 'lib/mail/mail.rb', line 153 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.
159 160 161 |
# File 'lib/mail/mail.rb', line 159 def self.first(*args, &block) retriever_method.first(*args, &block) end |
.inform_interceptors(mail) ⇒ Object
241 242 243 244 245 |
# File 'lib/mail/mail.rb', line 241 def self.inform_interceptors(mail) @@delivery_interceptors.each do |interceptor| interceptor.delivering_email(mail) end end |
.inform_observers(mail) ⇒ Object
235 236 237 238 239 |
# File 'lib/mail/mail.rb', line 235 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.
165 166 167 |
# File 'lib/mail/mail.rb', line 165 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:
= 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):
= 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
176 177 178 |
# File 'lib/mail/mail.rb', line 176 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
187 188 189 |
# File 'lib/mail/mail.rb', line 187 def Mail.read_from_string(mail_as_string) Mail.new(mail_as_string) end |
.register_autoload(name, path) ⇒ Object
54 55 56 57 |
# File 'lib/mail.rb', line 54 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.
223 224 225 226 227 |
# File 'lib/mail/mail.rb', line 223 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.
204 205 206 207 208 |
# File 'lib/mail/mail.rb', line 204 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
116 117 118 |
# File 'lib/mail/mail.rb', line 116 def self.retriever_method Configuration.instance.retriever_method end |
.unregister_interceptor(interceptor) ⇒ Object
Unregister the given interceptor, allowing mail to resume operations without it.
231 232 233 |
# File 'lib/mail/mail.rb', line 231 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.
212 213 214 |
# File 'lib/mail/mail.rb', line 212 def self.unregister_observer(observer) @@delivery_notification_observers.delete(observer) end |