Class: Mail::POP3

Inherits:
Retriever 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 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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Retriever

#all, #find_and_delete, #first, #last

Constructor Details

#initialize(values) ⇒ POP3

Returns a new instance of POP3.

[View source] [View on GitHub]

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

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

Instance Attribute Details

#settings ⇒ Object

Returns the value of attribute settings.

[View on GitHub]

48
49
50
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 48

def settings
  @settings
end

Instance Method Details

#connection(&block) ⇒ Object

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

Raises:

  • (ArgumentError)
[View source] [View on GitHub]

104
105
106
107
108
109
110
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 104

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

[View source] [View on GitHub]

94
95
96
97
98
99
100
101
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 94

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

#find(options = nil, &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.
[View source] [View on GitHub]

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/mail/network/retriever_methods/pop3.rb', line 60

def find(options = nil, &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