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)
  1. Call Net::POP3#start and start POP session.

  2. Access messages by using POP3#each_mail and/or POP3#mails.

  3. Close POP session by calling POP3#finish or use the block form of start.

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

address[R]

The address to connect to.

open_timeout[RW]

Seconds to wait until a connection is opened. If the POP3 object cannot open a connection within this time, it raises a TimeoutError exception.

port[R]

The port number to connect to.

read_timeout[R]

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

APOP(isapop) click to toggle source

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
auth_only(address, port = nil, account = nil, password = nil, isapop = false) click to toggle source

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
certs() click to toggle source
# File lib/net/pop.rb, line 355
def POP3.certs
  @certs
end
default_pop3_port() click to toggle source

The default port for POP3 connections, port 110

# File lib/net/pop.rb, line 210
def POP3.default_pop3_port
  110
end
default_pop3s_port() click to toggle source

The default port for POP3S connections, port 995

# File lib/net/pop.rb, line 215
def POP3.default_pop3s_port
  995
end
default_port() click to toggle source

Class Parameters

# File lib/net/pop.rb, line 205
def POP3.default_port
  default_pop3_port()
end
delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block) click to toggle source

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() click to toggle source

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(verify = OpenSSL::SSL::VERIFY_PEER, certs = nil) click to toggle source

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
foreach(address, port = nil, account = nil, password = nil, isapop = false) { |message| ... } click to toggle source

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
new(addr, port = nil, isapop = false) click to toggle source

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
start(address, port = nil, account = nil, password = nil, isapop = false) { |pop| ... } click to toggle source

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
use_ssl?() click to toggle source
# File lib/net/pop.rb, line 347
def POP3.use_ssl?
  @use_ssl
end
verify() click to toggle source
# File lib/net/pop.rb, line 351
def POP3.verify
  @verify
end

Public Instance Methods

active?()
Alias for: started?
apop?() click to toggle source

Does this instance use APOP authentication?

# File lib/net/pop.rb, line 416
def apop?
  @apop
end
auth_only(account, password) click to toggle source

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
delete_all() { |message| ... } click to toggle source

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
disable_ssl() click to toggle source
# File lib/net/pop.rb, line 440
def disable_ssl
  @use_ssl = false
  @verify = nil
  @certs = nil
end
each()
Alias for: each_mail
each_mail() { |message| ... } click to toggle source

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
Also aliased as: each
enable_ssl(verify = OpenSSL::SSL::VERIFY_PEER, certs = nil, port = POP3.default_pop3s_port) click to toggle source

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
finish() click to toggle source

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
inspect() click to toggle source

Provide human-readable stringification of class state.

# File lib/net/pop.rb, line 447
def inspect
  "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
end
logging(msg) click to toggle source
# File lib/net/pop.rb, line 680
def logging(msg)
  @debug_output << msg + "\n" if @debug_output
end
mails() click to toggle source

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
n_bytes() click to toggle source

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
n_mails() click to toggle source

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
read_timeout=(sec) click to toggle source

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
reset() click to toggle source

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
set_debug_output(arg) click to toggle source

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
start(account, password) { |pop| ... } click to toggle source

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
started?() click to toggle source

true if the POP3 session has started.

# File lib/net/pop.rb, line 491
def started?
  @started
end
Also aliased as: active?
use_ssl?() click to toggle source

does this instance use SSL?

# File lib/net/pop.rb, line 421
def use_ssl?
  @use_ssl
end

Private Instance Methods

command() click to toggle source
# File lib/net/pop.rb, line 580
def command
  raise IOError, 'POP session not opened yet' \
                                  if not @socket or @socket.closed?
  @command
end
do_finish() click to toggle source
# 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
do_start(account, password) click to toggle source
# 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
on_connect() click to toggle source
# File lib/net/pop.rb, line 559
def on_connect
end