Parent

Object

Class Index [+]

Quicksearch

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 first 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 37
37:     def initialize(values)
38:       self.settings = { :address              => "localhost",
39:                         :port                 => 110,
40:                         :user_name            => nil,
41:                         :password             => nil,
42:                         :authentication       => nil,
43:                         :enable_ssl           => false }.merge!(values)
44:     end

Public Instance Methods

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

Get all emails.

Possible options: 

  order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
    # File lib/mail/network/retriever_methods/pop3.rb, line 79
79:     def all(options = {}, &block)
80:       options ||= {}
81:       options[:count] = :all
82:       find(options, &block)
83:     end
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 156
156:     def connection(&block)
157:       raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?
158: 
159:       start do |pop3|
160:         yield pop3
161:       end
162:     end
delete_all() click to toggle source

Delete all emails from a POP3 server 

     # File lib/mail/network/retriever_methods/pop3.rb, line 146
146:     def delete_all
147:       start do |pop3|
148:         unless pop3.mails.empty?
149:           pop3.delete_all
150:           pop3.finish
151:         end
152:       end
153:     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 95
 95:     def find(options = {}, &block)
 96:       options = validate_options(options)
 97:       
 98:       start do |pop3|
 99:         mails = pop3.mails
100:         pop3.reset # Clears all "deleted" marks. This prevents non-explicit/accidental deletions due to server settings.
101:         mails.sort! { |m1, m2| m2.number <=> m1.number } if options[:what] == :last
102:         mails = mails.first(options[:count]) if options[:count].is_a? Integer
103:         
104:         if options[:what].to_sym == :last && options[:order].to_sym == :desc ||
105:            options[:what].to_sym == :first && options[:order].to_sym == :asc ||
106:           mails.reverse!
107:         end
108:         
109:         if block_given?
110:           mails.each do |mail|
111:             new_message = Mail.new(mail.pop)
112:             new_message.mark_for_delete = true if options[:delete_after_find]
113:             yield new_message
114:             mail.delete if options[:delete_after_find] && new_message.is_marked_for_delete? # Delete if still marked for delete
115:           end
116:         else
117:           emails = []
118:           mails.each do |mail|
119:             emails << Mail.new(mail.pop)
120:             mail.delete if options[:delete_after_find]
121:           end
122:           emails.size == 1 && options[:count] == 1 ? emails.first : emails
123:         end
124:         
125:       end
126:     end
find_and_delete(options = {}, &block) click to toggle source

Find emails in a POP3 mailbox, and then deletes them. Without any options, the five 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 true. Call #find if you would like this to default to false.
     # File lib/mail/network/retriever_methods/pop3.rb, line 139
139:     def find_and_delete(options = {}, &block)
140:       options ||= {}
141:       options[:delete_after_find] ||= true
142:       find(options, &block)      
143:     end
first(options = {}, &block) click to toggle source

Get the oldest received email(s)

Possible options: 

  count: number of emails to retrieve. The default value is 1.
  order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
    # File lib/mail/network/retriever_methods/pop3.rb, line 54
54:     def first(options = {}, &block)
55:       options ||= {}
56:       options[:what] = :first
57:       options[:count] ||= 1
58:       find(options, &block)
59:     end
last(options = {}, &block) click to toggle source

Get the most recent received email(s)

Possible options: 

  count: number of emails to retrieve. The default value is 1.
  order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
    # File lib/mail/network/retriever_methods/pop3.rb, line 67
67:     def last(options = {}, &block)
68:       options ||= {}
69:       options[:what] = :last
70:       options[:count] ||= 1
71:       find(options, &block)
72:     end

Private Instance Methods

start(config = Configuration.instance, &block) click to toggle source

Start a POP3 session and ensure that it will be closed in any case. Any messages marked for deletion via # or with the :delete_after_find option will be deleted when the session is closed. 

     # File lib/mail/network/retriever_methods/pop3.rb, line 179
179:     def start(config = Configuration.instance, &block)
180:       raise ArgumentError.new("Mail::Retrievable#pop3_start takes a block") unless block_given?
181:     
182:       pop3 = Net::POP3.new(settings[:address], settings[:port], isapop = false)
183:       pop3.enable_ssl(verify = OpenSSL::SSL::VERIFY_NONE) if settings[:enable_ssl]
184:       pop3.start(settings[:user_name], settings[:password])
185:     
186:       yield pop3
187:     ensure
188:       if defined?(pop3) && pop3 && pop3.started?
189:         pop3.finish
190:       end
191:     end
validate_options(options) click to toggle source

Set default options 

     # File lib/mail/network/retriever_methods/pop3.rb, line 167
167:     def validate_options(options)
168:       options ||= {}
169:       options[:count] ||= 10
170:       options[:order] ||= :asc
171:       options[:what]  ||= :first
172:       options[:delete_after_find] ||= false
173:       options
174:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.