Class: Mail::POP3

Inherits:
Object
  • Object
show all
Defined in:
lib/mail/network/retriever_methods/pop3.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(values) ⇒ POP3

Returns a new instance of POP3.



37
38
39
40
41
42
43
44
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 37

def initialize(values)
  self.settings = { :address              => "localhost",
                    :port                 => 110,
                    :user_name            => nil,
                    :password             => nil,
                    :authentication       => nil,
                    :enable_ssl           => false }.merge!(values)
end

Instance Attribute Details

#settings ⇒ Object

Returns the value of attribute settings.



46
47
48
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 46

def settings
  @settings
end

Instance Method Details

#all(options = {}, &block) ⇒ Object

Get all emails.

Possible options:

order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.



79
80
81
82
83
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 79

def all(options = {}, &block)
  options ||= {}
  options[:count] = :all
  find(options, &block)
end

#connection(&block) ⇒ Object

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

Raises:

  • (ArgumentError) 


156
157
158
159
160
161
162
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 156

def connection(&block)
  raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?

  start do |pop3|
    yield pop3
  end
end

#delete_all ⇒ Object

Delete all emails from a POP3 server



146
147
148
149
150
151
152
153
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 146

def delete_all
  start do |pop3|
    unless pop3.mails.empty?
      pop3.delete_all
      pop3.finish
    end
  end
end

#find(options = {}, &block) ⇒ Object

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.



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 95

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

#find_and_delete(options = {}, &block) ⇒ Object

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.



139
140
141
142
143
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 139

def find_and_delete(options = {}, &block)
  options ||= {}
  options[:delete_after_find] ||= true
  find(options, &block)      
end

#first(options = {}, &block) ⇒ Object

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.



54
55
56
57
58
59
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 54

def first(options = {}, &block)
  options ||= {}
  options[:what] = :first
  options[:count] ||= 1
  find(options, &block)
end

#last(options = {}, &block) ⇒ Object

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.



67
68
69
70
71
72
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 67

def last(options = {}, &block)
  options ||= {}
  options[:what] = :last
  options[:count] ||= 1
  find(options, &block)
end