Net::POP3

Class

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 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.

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

svn revision of this library

Attributes

address

Read

The address to connect to.

open_timeout

Read & Write

Seconds to wait until a connection is opened. If the POP3 object cannot open a connection within this time, it raises a Net::OpenTimeout exception. The default value is 30 seconds.

read_timeout

Read

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 Net::ReadTimeout exception. The default value is 60 seconds.

Class Methods

APOP(isapop)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 239
def POP3.APOP(isapop)
  isapop ? APOP : POP3
end

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

auth_only(address, port = nil, account = nil, password = nil, isapop = false)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 306
def POP3.auth_only(address, port = nil,
                   account = nil, password = nil,
                   isapop = false)
  new(address, port, isapop).auth_only account, password
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)

certs

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 378
def POP3.certs
  return @ssl_params[:ca_file] || @ssl_params[:ca_path]
end

returns the :ca_file or :ca_path from POP3.ssl_params

create_ssl_params(verify_or_params = {}, certs = nil)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 338
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

Constructs proper parameters from arguments

default_pop3_port

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 211
def POP3.default_pop3_port
  110
end

The default port for POP3 connections, port 110

default_pop3s_port

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 216
def POP3.default_pop3s_port
  995
end

The default port for POP3S connections, port 995

default_port

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 206
def POP3.default_port
  default_pop3_port()
end

returns the port for POP3

delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 284
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

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

disable_ssl

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 356
def POP3.disable_ssl
  @ssl_params = nil
end

Disable SSL for all new instances.

Net::POP.enable_ssl(params = {})

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 333
def POP3.enable_ssl(*args)
  @ssl_params = create_ssl_params(*args)
end

Enable SSL for all new instances. params is passed to OpenSSL::SSLContext#set_params.

foreach(address, port = nil, account = nil, password = nil, isapop = false) { |message| ... }

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 263
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

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

new(addr, port = nil, isapop = false)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 418
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

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.

ssl_params

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 363
def POP3.ssl_params
  return @ssl_params
end

returns the SSL Parameters

start(address, port = nil, account = nil, password = nil, isapop = false) { |pop| ... }

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 402
def POP3.start(address, port = nil,
               account = nil, password = nil,
               isapop = false, &block)   # :yield: pop
  new(address, port, isapop).start(account, password, &block)
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

use_ssl?

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 368
def POP3.use_ssl?
  return !@ssl_params.nil?
end

returns true if POP3.ssl_params is set

verify

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 373
def POP3.verify
  return @ssl_params[:verify_mode]
end

returns whether verify_mode is enable from POP3.ssl_params

Instance Methods

apop?

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 437
def apop?
  @apop
end

Does this instance use APOP authentication?

auth_only(account, password)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 315
def auth_only(account, password)
  raise IOError, 'opening previously opened POP session' if started?
  start(account, password) {
    ;
  }
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.

delete_all() { |message| ... }

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 687
def delete_all # :yield: message
  mails().each do |m|
    yield m if block_given?
    m.delete unless m.deleted?
  end
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.

disable_ssl

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 464
def disable_ssl
  @ssl_params = nil
end

Disable SSL for all new instances.

each

lib/net/pop.rb View on GitHub

An alias for each_mail

each_mail() { |message| ... }

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 665
def each_mail(&block)  # :yield: message
  mails().each(&block)
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.

Net::POP#enable_ssl(params = {})

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 453
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

Enables SSL for this instance. Must be called before the connection is established to have any effect. params[:port] is port to establish the SSL connection on; Defaults to 995. params (except :port) is passed to OpenSSL::SSLContext#set_params.

finish

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 586
def finish
  raise IOError, 'POP session not yet started' unless started?
  do_finish
end

Finishes a POP3 session and closes TCP connection.

inspect

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 469
def inspect
  "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
end

Provide human-readable stringification of class state.

logging(msg)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 712
def logging(msg)
  @debug_output << msg + "\n" if @debug_output
end

debugging output for msg

mails

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 643
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 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.

n_bytes

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 631
def n_bytes
  return @n_bytes if @n_bytes
  @n_mails, @n_bytes = command().stat
  @n_bytes
end

Returns the total size in bytes of all the messages on the POP server.

n_mails

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 624
def n_mails
  return @n_mails if @n_mails
  @n_mails, @n_bytes = command().stat
  @n_mails
end

Returns the number of messages on the POP server.

port

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 494
def port
  return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
end

The port number to connect to.

read_timeout=(sec)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 509
def read_timeout=(sec)
  @command.socket.read_timeout = sec if @command
  @read_timeout = sec
end

Set the read timeout.

reset

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 697
def reset
  command().rset
  mails().each do |m|
    m.instance_eval {
      @deleted = false
    }
  end
end

Resets the session. This clears all “deleted” marks from messages.

This method raises a POPError if an error occurs.

set_debug_output(arg)

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 486
def set_debug_output(arg)
  @debug_output = arg
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

start(account, password) { |pop| ... }

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 527
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

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.

started?

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 515
def started?
  @started
end

true if the POP3 session has started.

use_ssl?

lib/net/pop.rb View on GitHub

          
            # File tmp/rubies/ruby-2.3.8/lib/net/pop.rb, line 442
def use_ssl?
  return !@ssl_params.nil?
end

does this instance use SSL?

Net::POP3

What is This Library?

Examples

Retrieving Messages

Shortened Code

Memory Space Issues

Using APOP

Fetch Only Selected Mail Using ‘UIDL’ POP Command

Revision

address

open_timeout

read_timeout

APOP(isapop)

auth_only(address, port = nil, account = nil, password = nil, isapop = false)

Example: normal POP3

Example: APOP

certs

create_ssl_params(verify_or_params = {}, certs = nil)

default_pop3_port

default_pop3s_port

default_port

delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block)

Example

disable_ssl

Net::POP.enable_ssl(params = {})

foreach(address, port = nil, account = nil, password = nil, isapop = false) { |message| ... }

Example

new(addr, port = nil, isapop = false)

ssl_params

start(address, port = nil, account = nil, password = nil, isapop = false) { |pop| ... }

Example

use_ssl?

verify

apop?

auth_only(account, password)

delete_all() { |message| ... }

Example

disable_ssl

each

each_mail() { |message| ... }

Net::POP#enable_ssl(params = {})

finish

inspect

logging(msg)

mails

n_bytes

n_mails

port

read_timeout=(sec)

reset

set_debug_output(arg)

Example

start(account, password) { |pop| ... }

started?

use_ssl?

Using `APOP`

Example: normal `POP3`

Example: `APOP`