Protocol
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).
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 start POP session.
Access messages by using POP3#each_mail and/or POP3#mails.
Close POP session by calling POP3#finish or use the block form of start.
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
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
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
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.
Seconds to wait until a connection is opened. If the POP3 object cannot open a connection within this time, it raises a TimeoutError exception.
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.
Opens a POP3 session, attempts authentication, and quits.
This method raises POPAuthenticationError if authentication fails.
Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword')
Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword', true)
# File 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 net/pop.rb, line 370
def POP3.certs
return @ssl_params[:ca_file] || @ssl_params[:ca_path]
end
# File net/pop.rb, line 336
def POP3.create_ssl_params(verify_or_params = {}, certs = nil)
begin
params = verify_or_params.to_hash
rescue NoMethodError
params = {}
params[:verify_mode] = verify_or_params
if certs
if File.file?(certs)
params[:ca_file] = certs
elsif File.directory?(certs)
params[:ca_path] = certs
end
end
end
return params
end
The default port for POP3 connections, port 110
# File net/pop.rb, line 210
def POP3.default_pop3_port
110
end
The default port for POP3S connections, port 995
# File net/pop.rb, line 215
def POP3.default_pop3s_port
995
end
Class Parameters
# File 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.
Net::POP3.delete_all('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop end
# File 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 net/pop.rb, line 354
def POP3.disable_ssl
@ssl_params = nil
end
Enable SSL for all new instances. params is passed to OpenSSL::SSLContext#set_params.
# File net/pop.rb, line 332
def POP3.enable_ssl(*args)
@ssl_params = create_ssl_params(*args)
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.
Net::POP3.foreach('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop m.delete if $DELETE end
# File 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 net/pop.rb, line 410
def initialize(addr, port = nil, isapop = false)
@address = addr
@ssl_params = POP3.ssl_params
@port = port
@apop = isapop
@command = nil
@socket = nil
@started = false
@open_timeout = 30
@read_timeout = 60
@debug_output = nil
@mails = nil
@n_mails = nil
@n_bytes = nil
end
# File net/pop.rb, line 358
def POP3.ssl_params
return @ssl_params
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.
Net::POP3.start(addr, port, account, password) do |pop| pop.each_mail do |m| file.write m.pop m.delete end end
# File net/pop.rb, line 394
def POP3.start(address, port = nil,
account = nil, password = nil,
isapop = false, &block) # :yield: pop
new(address, port, isapop).start(account, password, &block)
end
Does this instance use APOP authentication?
# File net/pop.rb, line 429
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 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.
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 net/pop.rb, line 666
def delete_all # :yield: message
mails().each do |m|
yield m if block_given?
m.delete unless m.deleted?
end
end
# File net/pop.rb, line 455
def disable_ssl
@ssl_params = 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 net/pop.rb, line 644
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. +params+ is port to establish the SSL connection on; Defaults to 995. params (except :port) is passed to OpenSSL::SSLContext#set_params.
# File net/pop.rb, line 445
def enable_ssl(verify_or_params = {}, certs = nil, port = nil)
begin
@ssl_params = verify_or_params.to_hash.dup
@port = @ssl_params.delete(:port) || @port
rescue NoMethodError
@ssl_params = POP3.create_ssl_params(verify_or_params, certs)
@port = port || @port
end
end
Finishes a POP3 session and closes TCP connection.
# File net/pop.rb, line 573
def finish
raise IOError, 'POP session not yet started' unless started?
do_finish
end
Provide human-readable stringification of class state.
# File net/pop.rb, line 460
def inspect
"#<#{self.class} #{@address}:#{@port} open=#{@started}>"
end
# File net/pop.rb, line 690
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 net/pop.rb, line 622
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 net/pop.rb, line 610
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 net/pop.rb, line 603
def n_mails
return @n_mails if @n_mails
@n_mails, @n_bytes = command().stat
@n_mails
end
The port number to connect to.
# File net/pop.rb, line 485
def port
return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
end
Set the read timeout.
# File net/pop.rb, line 500
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 net/pop.rb, line 676
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.
pop = Net::POP.new(addr, port) pop.set_debug_output $stderr pop.start(account, passwd) do |pop| .... end
# File net/pop.rb, line 477
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 net/pop.rb, line 518
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