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/header.rb,
lib/mail/message.rb,
lib/mail/version.rb,
lib/mail/envelope.rb,
lib/mail/patterns.rb,
lib/mail/utilities.rb,
lib/mail/field_list.rb,
lib/mail/parts_list.rb,
lib/mail/configuration.rb,
lib/mail/fields/cc_field.rb,
lib/mail/fields/to_field.rb,
lib/mail/parsers/rfc2045.rb,
lib/mail/parsers/rfc2822.rb,
lib/mail/attachments_list.rb,
lib/mail/elements/address.rb,
lib/mail/encodings/base64.rb,
lib/mail/fields/bcc_field.rb,
lib/mail/parsers/received.rb,
lib/mail/fields/date_field.rb,
lib/mail/fields/from_field.rb,
lib/mail/parsers/date_time.rb,
lib/mail/encodings/encodings.rb,
lib/mail/fields/sender_field.rb,
lib/mail/parsers/message_ids.rb,
lib/mail/elements/phrase_list.rb,
lib/mail/fields/subject_field.rb,
lib/mail/parsers/content_type.rb,
lib/mail/parsers/mime_version.rb,
lib/mail/parsers/phrase_lists.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/parsers/address_lists.rb,
lib/mail/parsers/envelope_from.rb,
lib/mail/fields/resent_cc_field.rb,
lib/mail/fields/resent_to_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/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/parsers/content_location.rb,
lib/mail/parsers/rfc2822_obsolete.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/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/parsers/content_disposition.rb,
lib/mail/elements/message_ids_element.rb,
lib/mail/fields/common/common_address.rb,
lib/mail/fields/common/parameter_hash.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/smtp.rb,
lib/mail/elements/envelope_from_element.rb,
lib/mail/fields/resent_message_id_field.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/parsers/content_transfer_encoding.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/elements/content_transfer_encoding_element.rb

Defined Under Namespace

Modules: AddressLists, CommonAddress, CommonDate, CommonField, CommonMessageId, ContentDisposition, ContentLocation, ContentTransferEncoding, ContentType, DateTime, Encodings, EnvelopeFrom, MessageIds, MimeVersion, 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, Field, FieldList, FileDelivery, FromField, Header, IMAP, InReplyToField, 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, ReturnPathField, Ruby18, Ruby19, SMTP, SenderField, Sendmail, StructuredField, SubjectField, TestMailer, ToField, UnknownEncodingType, UnstructuredField

Constant Summary collapse

RubyVer = 
Mail::Ruby18

Class Method Summary collapse

Class Method Details

.all(*args, &block) ⇒ Object

Receive all emails from a POP3 server. See Mail::POP3 for a complete documentation.



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

def Mail.all(*args, &block)
  retriever_method.all(*args, &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



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

def Mail.defaults(&block)
  Mail::Configuration.instance.instance_eval(&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 Mail.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.



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

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

.delivery_method ⇒ Object

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



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

def Mail.delivery_method
  Mail::Configuration.instance.delivery_method
end

.find(*args, &block) ⇒ Object

Find emails in a POP3 server. See Mail::POP3 for a complete documentation.



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

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

.first(*args, &block) ⇒ Object

Receive the first email(s) from a Pop3 server. See Mail::POP3 for a complete documentation.



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

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

.last(*args, &block) ⇒ Object

Receive the first email(s) from a Pop3 server. See Mail::POP3 for a complete documentation.



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

def Mail.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\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'



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

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

.read(filename) ⇒ Object

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



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

def Mail.read(filename)
  Mail.new(File.read(filename))
end

.retriever_method ⇒ Object

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



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

def Mail.retriever_method
  Mail::Configuration.instance.retriever_method
end