Class: Mail::POP3

### Home Classes Methods

### In Files

- lib/mail/network/retriever_methods/pop3.rb

### Parent

Mail::Retriever

### Methods

- ::new
- #connection
- #delete_all
- #find

### Files

- TODO.rdoc

### Class/Module Index

Quicksearch

- Mail
- Mail::Address
- Mail::AddressContainer
- Mail::AttachmentsList
- Mail::BccField
- Mail::Body
- Mail::CcField
- Mail::CheckDeliveryParams
- Mail::CommentsField
- Mail::Constants
- Mail::ContentDescriptionField
- Mail::ContentDispositionField
- Mail::ContentIdField
- Mail::ContentLocationField
- Mail::ContentTransferEncodingElement
- Mail::ContentTransferEncodingField
- Mail::ContentTypeField
- Mail::DateField
- Mail::Encodings
- Mail::Encodings::Base64
- Mail::Encodings::Binary
- Mail::Encodings::EightBit
- Mail::Encodings::QuotedPrintable
- Mail::Encodings::SevenBit
- Mail::Encodings::TransferEncoding
- Mail::Encodings::UnixToUnix
- Mail::Envelope
- Mail::EnvelopeFromElement
- Mail::Exim
- Mail::Field
- Mail::Field::FieldError
- Mail::FieldList
- Mail::FileDelivery
- Mail::FromField
- Mail::Header
- Mail::IMAP
- Mail::InReplyToField
- Mail::IndifferentHash
- Mail::KeywordsField
- Mail::Matchers
- Mail::Matchers::HasSentEmailMatcher
- Mail::MessageIdField
- Mail::MessageIdsElement
- Mail::MimeVersionElement
- Mail::MimeVersionField
- Mail::Multibyte
- Mail::Multibyte::EncodingError
- Mail::OptionalField
- Mail::POP3
- Mail::ParameterHash
- Mail::Parsers
- Mail::Parsers::AddressListsParser
- Mail::Parsers::ContentDispositionParser
- Mail::Parsers::ContentLocationParser
- Mail::Parsers::ContentTransferEncodingParser
- Mail::Parsers::ContentTypeParser
- Mail::Parsers::DateTimeParser
- Mail::Parsers::EnvelopeFromParser
- Mail::Parsers::MessageIdsParser
- Mail::Parsers::MimeVersionParser
- Mail::Parsers::PhraseListsParser
- Mail::Parsers::Ragel
- Mail::Parsers::Ragel::AddressListsMachine
- Mail::Parsers::Ragel::ContentDispositionMachine
- Mail::Parsers::Ragel::ContentLocationMachine
- Mail::Parsers::Ragel::ContentTransferEncodingMachine
- Mail::Parsers::Ragel::ContentTypeMachine
- Mail::Parsers::Ragel::DateTimeMachine
- Mail::Parsers::Ragel::EnvelopeFromMachine
- Mail::Parsers::Ragel::MessageIdsMachine
- Mail::Parsers::Ragel::MimeVersionMachine
- Mail::Parsers::Ragel::PhraseListsMachine
- Mail::Parsers::Ragel::ReceivedMachine
- Mail::Parsers::Ragel::Ruby
- Mail::Parsers::ReceivedParser
- Mail::Part
- Mail::PartsList
- Mail::PhraseList
- Mail::ReceivedElement
- Mail::ReceivedField
- Mail::ReferencesField
- Mail::ReplyToField
- Mail::ResentBccField
- Mail::ResentCcField
- Mail::ResentDateField
- Mail::ResentFromField
- Mail::ResentMessageIdField
- Mail::ResentSenderField
- Mail::ResentToField
- Mail::Retriever
- Mail::ReturnPathField
- Mail::Ruby18
- Mail::Ruby19
- Mail::Ruby19::BestEffortCharsetEncoder
- Mail::Ruby19::StrictCharsetEncoder
- Mail::SMTP
- Mail::SMTPConnection
- Mail::SenderField
- Mail::Sendmail
- Mail::StructuredField
- Mail::SubjectField
- Mail::TestMailer
- Mail::TestRetriever
- Mail::ToField
- Mail::UnstructuredField
- Mail::Utilities
- Mail::VERSION
- Net
- Net::SMTP
- Object
- String

No matching classes.

# Mail::POP3

The Pop3 retriever allows to get the last, first or all emails from a POP3 server. Each email retrieved (RFC2822) is given as an instance of `Message`.

While being retrieved, emails can be yielded if a block is given.

### Example of retrieving Emails from GMail:

    Mail.defaults do
      retriever_method :pop3, { :address             => "pop.gmail.com",
                                :port                => 995,
                                :user_name           => '<username>',
                                :password            => '<password>',
                                :enable_ssl          => true }
    end

    Mail.all    #=> Returns an array of all emails
    Mail.first  #=> Returns the first unread email
    Mail.last   #=> Returns the last unread email

You can also pass options into Mail.find to locate an email in your pop mailbox with the following options:

    what:  last or first emails. The default is :first.
    order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
    count: number of emails to retrieve. The default value is 10. A value of 1 returns an
           instance of Message, not an array of Message instances.

    Mail.find(:what => :first, :count => 10, :order => :asc)
    #=> Returns the first 10 emails in ascending order

### Attributes

settings[RW]

### Public Class Methods

new(values) click to toggle source

    # File lib/mail/network/retriever_methods/pop3.rb, line 36
    def initialize(values)
      self.settings = { :address              => "localhost",
                        :port                 => 110,
                        :user_name            => nil,
                        :password             => nil,
                        :authentication       => nil,
                        :enable_ssl           => false }.merge!(values)
    end

### Public Instance Methods

connection(&block) click to toggle source

Returns the connection object of the retrievable (IMAP or POP3)

    # File lib/mail/network/retriever_methods/pop3.rb, line 101
    def connection(&block)
      raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?

      start do |pop3|
        yield pop3
      end
    end

delete_all() click to toggle source

Delete all emails from a POP3 server

    # File lib/mail/network/retriever_methods/pop3.rb, line 91
    def delete_all
      start do |pop3|
        unless pop3.mails.empty?
          pop3.delete_all
          pop3.finish
        end
      end
    end

find(options = {}, &block) click to toggle source

Find emails in a POP3 mailbox. Without any options, the 5 last received emails are returned.

Possible options:

    what:  last or first emails. The default is :first.
    order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
    count: number of emails to retrieve. The default value is 10. A value of 1 returns an
           instance of Message, not an array of Message instances.
    delete_after_find: flag for whether to delete each retreived email after find. Default
            is false. Use #find_and_delete if you would like this to default to true.

    # File lib/mail/network/retriever_methods/pop3.rb, line 57
    def find(options = {}, &block)
      options = validate_options(options)

      start do |pop3|
        mails = pop3.mails
        pop3.reset # Clears all "deleted" marks. This prevents non-explicit/accidental deletions due to server settings.
        mails.sort! { |m1, m2| m2.number <=> m1.number } if options[:what] == :last
        mails = mails.first(options[:count]) if options[:count].is_a? Integer

        if options[:what].to_sym == :last && options[:order].to_sym == :desc ||
           options[:what].to_sym == :first && options[:order].to_sym == :asc ||
          mails.reverse!
        end

        if block_given?
          mails.each do |mail|
            new_message = Mail.new(mail.pop)
            new_message.mark_for_delete = true if options[:delete_after_find]
            yield new_message
            mail.delete if options[:delete_after_find] && new_message.is_marked_for_delete? # Delete if still marked for delete
          end
        else
          emails = []
          mails.each do |mail|
            emails << Mail.new(mail.pop)
            mail.delete if options[:delete_after_find]
          end
          emails.size == 1 && options[:count] == 1 ? emails.first : emails
        end

      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.