class Net::POP
Net::POP3
¶ ↑
What is This Library?¶ ↑
This library provides functionality for retrieving email via POP3
, the Post Office Protocol version 3. For details of POP3
, see [RFC1939] (www.ietf.org/rfc/rfc1939.txt).
Examples¶ ↑
Retrieving Messages ¶ ↑
This example retrieves messages from the server and deletes them on the server.
Messages are written to files named 'inbox/1', 'inbox/2', .… Replace 'pop.example.com' with your POP3
server address, and 'YourAccount' and 'YourPassword' with the appropriate account details.
require 'net/pop' pop = Net::POP3.new('pop.example.com') pop.start('YourAccount', 'YourPassword') # (1) if pop.mails.empty? puts 'No mail.' else i = 0 pop.each_mail do |m| # or "pop.mails.each ..." # (2) File.open("inbox/#{i}", 'w') do |f| f.write m.pop end m.delete i += 1 end puts "#{pop.mails.size} mails popped." end pop.finish # (3)
-
Call
Net::POP3#start
and startPOP
session. -
Access messages by using
POP3#each_mail
and/orPOP3#mails
. -
Close
POP
session by callingPOP3#finish
or use the block form ofstart
.
Shortened Code¶ ↑
The example above is very verbose. You can shorten the code by using some utility methods. First, the block form of Net::POP3.start
can be used instead of POP3.new
, POP3#start
and POP3#finish
.
require 'net/pop' Net::POP3.start('pop.example.com', 110, 'YourAccount', 'YourPassword') do |pop| if pop.mails.empty? puts 'No mail.' else i = 0 pop.each_mail do |m| # or "pop.mails.each ..." File.open("inbox/#{i}", 'w') do |f| f.write m.pop end m.delete i += 1 end puts "#{pop.mails.size} mails popped." end end
POP3#delete_all
is an alternative for each_mail
and delete.
require 'net/pop' Net::POP3.start('pop.example.com', 110, 'YourAccount', 'YourPassword') do |pop| if pop.mails.empty? puts 'No mail.' else i = 1 pop.delete_all do |m| File.open("inbox/#{i}", 'w') do |f| f.write m.pop end i += 1 end end end
And here is an even shorter example.
require 'net/pop' i = 0 Net::POP3.delete_all('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| File.open("inbox/#{i}", 'w') do |f| f.write m.pop end i += 1 end
Memory Space Issues¶ ↑
All the examples above get each message as one big string. This example avoids this.
require 'net/pop' i = 1 Net::POP3.delete_all('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| File.open("inbox/#{i}", 'w') do |f| m.pop do |chunk| # get a message little by little. f.write chunk end i += 1 end end
Using APOP
¶ ↑
The net/pop library supports APOP
authentication. To use APOP
, use the Net::APOP
class instead of the Net::POP3
class. You can use the utility method, Net::POP3
.APOP(). For example:
require 'net/pop' # Use APOP authentication if $isapop == true pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110) pop.start(YourAccount', 'YourPassword') do |pop| # Rest of the code is the same. end
Fetch Only Selected Mail Using 'UIDL' POP
Command¶ ↑
If your POP
server provides UIDL functionality, you can grab only selected mails from the POP
server. e.g.
def need_pop?( id ) # determine if we need pop this mail... end Net::POP3.start('pop.example.com', 110, 'Your account', 'Your password') do |pop| pop.mails.select { |m| need_pop?(m.unique_id) }.each do |m| do_something(m.pop) end end
The POPMail#unique_id()
method returns the unique-id of the message as a String. Normally the unique-id is a hash of the message.
Constants
- Revision
Attributes
The address to connect to.
Seconds to wait until a connection is opened. If the POP3
object cannot open a connection within this time, it raises a TimeoutError exception.
The port number to connect to.
Seconds to wait until reading one block (by one read(1) call). If the POP3
object cannot complete a read() within this time, it raises a TimeoutError exception.
Public Class Methods
Returns the APOP
class if isapop
is true; otherwise, returns the POP
class. For example:
# Example 1 pop = Net::POP3::APOP($is_apop).new(addr, port) # Example 2 Net::POP3::APOP($is_apop).start(addr, port) do |pop| .... end
# File lib/net/pop.rb, line 238 def POP3.APOP(isapop) isapop ? APOP : POP3 end
Opens a POP3
session, attempts authentication, and quits.
This method raises POPAuthenticationError
if authentication fails.
Example: normal POP3
¶ ↑
Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword')
Example: APOP
¶ ↑
Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword', true)
# File lib/net/pop.rb, line 305 def POP3.auth_only(address, port = nil, account = nil, password = nil, isapop = false) new(address, port, isapop).auth_only account, password end
# File lib/net/pop.rb, line 355 def POP3.certs @certs end
The default port for POP3
connections, port 110
# File lib/net/pop.rb, line 210 def POP3.default_pop3_port 110 end
The default port for POP3S connections, port 995
# File lib/net/pop.rb, line 215 def POP3.default_pop3s_port 995 end
Class Parameters
# File lib/net/pop.rb, line 205 def POP3.default_port default_pop3_port() end
Starts a POP3
session and deletes all messages on the server. If a block is given, each POPMail
object is yielded to it before being deleted.
This method raises a POPAuthenticationError
if authentication fails.
Example¶ ↑
Net::POP3.delete_all('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop end
# File lib/net/pop.rb, line 283 def POP3.delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block) start(address, port, account, password, isapop) {|pop| pop.delete_all(&block) } end
Disable SSL for all new instances.
# File lib/net/pop.rb, line 341 def POP3.disable_ssl @use_ssl = nil @verify = nil @certs = nil end
Enable SSL for all new instances. verify
is the type of verification to do on the Server Cert; Defaults to OpenSSL::SSL::VERIFY_PEER. certs
is a file or directory holding CA certs to use to verify the server cert; Defaults to nil.
# File lib/net/pop.rb, line 334 def POP3.enable_ssl(verify = OpenSSL::SSL::VERIFY_PEER, certs = nil) @use_ssl = true @verify = verify @certs = certs end
Starts a POP3
session and iterates over each POPMail
object, yielding it to the block
. This method is equivalent to:
Net::POP3.start(address, port, account, password) do |pop| pop.each_mail do |m| yield m end end
This method raises a POPAuthenticationError
if authentication fails.
Example¶ ↑
Net::POP3.foreach('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop m.delete if $DELETE end
# File lib/net/pop.rb, line 262 def POP3.foreach(address, port = nil, account = nil, password = nil, isapop = false, &block) # :yields: message start(address, port, account, password, isapop) {|pop| pop.each_mail(&block) } end
Creates a new POP3
object.
address
is the hostname or ip address of your POP3
server.
The optional port
is the port to connect to.
The optional isapop
specifies whether this connection is going to use APOP
authentication; it defaults to false
.
This method does not open the TCP connection.
# File lib/net/pop.rb, line 395 def initialize(addr, port = nil, isapop = false) @address = addr @use_ssl = POP3.use_ssl? @port = port || (POP3.use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port) @apop = isapop @certs = POP3.certs @verify = POP3.verify @command = nil @socket = nil @started = false @open_timeout = 30 @read_timeout = 60 @debug_output = nil @mails = nil @n_mails = nil @n_bytes = nil end
Creates a new POP3
object and open the connection. Equivalent to
Net::POP3.new(address, port, isapop).start(account, password)
If block
is provided, yields the newly-opened POP3
object to it, and automatically closes it at the end of the session.
Example¶ ↑
Net::POP3.start(addr, port, account, password) do |pop| pop.each_mail do |m| file.write m.pop m.delete end end
# File lib/net/pop.rb, line 379 def POP3.start(address, port = nil, account = nil, password = nil, isapop = false, &block) # :yield: pop new(address, port, isapop).start(account, password, &block) end
# File lib/net/pop.rb, line 347 def POP3.use_ssl? @use_ssl end
# File lib/net/pop.rb, line 351 def POP3.verify @verify end
Public Instance Methods
Does this instance use APOP
authentication?
# File lib/net/pop.rb, line 416 def apop? @apop end
Starts a pop3 session, attempts authentication, and quits. This method must not be called while POP3
session is opened. This method raises POPAuthenticationError
if authentication fails.
# File lib/net/pop.rb, line 314 def auth_only(account, password) raise IOError, 'opening previously opened POP session' if started? start(account, password) { ; } end
Deletes all messages on the server.
If called with a block, yields each message in turn before deleting it.
Example¶ ↑
n = 1 pop.delete_all do |m| File.open("inbox/#{n}") do |f| f.write m.pop end n += 1 end
This method raises a POPError
if an error occurs.
# File lib/net/pop.rb, line 655 def delete_all # :yield: message mails().each do |m| yield m if block_given? m.delete unless m.deleted? end end
# File lib/net/pop.rb, line 440 def disable_ssl @use_ssl = false @verify = nil @certs = nil end
Yields each message to the passed-in block in turn. Equivalent to:
pop3.mails.each do |popmail| .... end
This method raises a POPError
if an error occurs.
# File lib/net/pop.rb, line 633 def each_mail(&block) # :yield: message mails().each(&block) end
Enables SSL for this instance. Must be called before the connection is established to have any effect. verify
is the type of verification to do on the Server Cert; Defaults to OpenSSL::SSL::VERIFY_PEER. certs
is a file or directory holding CA certs to use to verify the server cert; Defaults to nil. port
is port to establish the SSL connection on; Defaults to 995.
# File lib/net/pop.rb, line 432 def enable_ssl(verify = OpenSSL::SSL::VERIFY_PEER, certs = nil, port = POP3.default_pop3s_port) @use_ssl = true @verify = verify @certs = certs @port = port end
Finishes a POP3
session and closes TCP connection.
# File lib/net/pop.rb, line 564 def finish raise IOError, 'POP session not yet started' unless started? do_finish end
Provide human-readable stringification of class state.
# File lib/net/pop.rb, line 447 def inspect "#<#{self.class} #{@address}:#{@port} open=#{@started}>" end
# File lib/net/pop.rb, line 680 def logging(msg) @debug_output << msg + "\n" if @debug_output end
Returns an array of Net::POPMail
objects, representing all the messages on the server. This array is renewed when the session restarts; otherwise, it is fetched from the server the first time this method is called (directly or indirectly) and cached.
This method raises a POPError
if an error occurs.
# File lib/net/pop.rb, line 611 def mails return @mails.dup if @mails if n_mails() == 0 # some popd raises error for LIST on the empty mailbox. @mails = [] return [] end @mails = command().list.map {|num, size| POPMail.new(num, size, self, command()) } @mails.dup end
Returns the total size in bytes of all the messages on the POP
server.
# File lib/net/pop.rb, line 599 def n_bytes return @n_bytes if @n_bytes @n_mails, @n_bytes = command().stat @n_bytes end
Returns the number of messages on the POP
server.
# File lib/net/pop.rb, line 592 def n_mails return @n_mails if @n_mails @n_mails, @n_bytes = command().stat @n_mails end
Set the read timeout.
# File lib/net/pop.rb, line 485 def read_timeout=(sec) @command.socket.read_timeout = sec if @command @read_timeout = sec end
Resets the session. This clears all “deleted” marks from messages.
This method raises a POPError
if an error occurs.
# File lib/net/pop.rb, line 665 def reset command().rset mails().each do |m| m.instance_eval { @deleted = false } end end
WARNING: This method causes a serious security hole. Use this method only for debugging.
Set an output stream for debugging.
Example¶ ↑
pop = Net::POP.new(addr, port) pop.set_debug_output $stderr pop.start(account, passwd) do |pop| .... end
# File lib/net/pop.rb, line 464 def set_debug_output(arg) @debug_output = arg end
Starts a POP3
session.
When called with block, gives a POP3
object to the block and closes the session after block call finishes.
This method raises a POPAuthenticationError
if authentication fails.
# File lib/net/pop.rb, line 503 def start(account, password) # :yield: pop raise IOError, 'POP session already started' if @started if block_given? begin do_start account, password return yield(self) ensure do_finish end else do_start account, password return self end end
true
if the POP3
session has started.
# File lib/net/pop.rb, line 491 def started? @started end
does this instance use SSL?
# File lib/net/pop.rb, line 421 def use_ssl? @use_ssl end
Private Instance Methods
# File lib/net/pop.rb, line 580 def command raise IOError, 'POP session not opened yet' \ if not @socket or @socket.closed? @command end
# File lib/net/pop.rb, line 569 def do_finish @mails = nil @command.quit if @command ensure @started = false @command = nil @socket.close if @socket and not @socket.closed? @socket = nil end
# File lib/net/pop.rb, line 518 def do_start(account, password) s = timeout(@open_timeout) { TCPSocket.open(@address, @port) } if use_ssl? raise 'openssl library not installed' unless defined?(OpenSSL) context = OpenSSL::SSL::SSLContext.new context.verify_mode = @verify if @certs if File.file?(@certs) context.ca_file = @certs elsif File.directory?(@certs) context.ca_path = @certs else raise ArgumentError, "certs path is not file/directory: #{@certs}" end end s = OpenSSL::SSL::SSLSocket.new(s, context) s.sync_close = true s.connect end @socket = InternetMessageIO.new(s) logging "POP session started: #{@address}:#{@port} (#{@apop ? 'APOP' : 'POP'})" @socket.read_timeout = @read_timeout @socket.debug_output = @debug_output on_connect @command = POP3Command.new(@socket) if apop? @command.apop account, password else @command.auth account, password end @started = true ensure # Authentication failed, clean up connection. unless @started s.close if s and not s.closed? @socket = nil @command = nil end end
# File lib/net/pop.rb, line 559 def on_connect end