class Net::POP3 - RDoc Documentation

# class 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($isapop).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

VERSION

  version of this library

### 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 `Net::OpenTimeout` exception. The default value is 30 seconds.

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

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

returns the :ca_file or :ca_path from `POP3.ssl_params`

    # File lib/net/pop.rb, line 377
    def POP3.certs
      return @ssl_params[:ca_file] || @ssl_params[:ca_path]
    end

create_ssl_params(verify_or_params = {}, certs = nil) click to toggle source

Constructs proper parameters from arguments

    # File lib/net/pop.rb, line 337
    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

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

returns the port for `POP3`

    # 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 355
    def POP3.disable_ssl
      @ssl_params = nil
    end

Net::POP.enable_ssl(params = {}) click to toggle source

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

    # File lib/net/pop.rb, line 332
    def POP3.enable_ssl(*args)
      @ssl_params = create_ssl_params(*args)
    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 417
    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

ssl_params() click to toggle source

returns the SSL Parameters

see also `POP3.enable_ssl`

    # File lib/net/pop.rb, line 362
    def POP3.ssl_params
      return @ssl_params
    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 401
    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

returns `true` if `POP3.ssl_params` is set

    # File lib/net/pop.rb, line 367
    def POP3.use_ssl?
      return !@ssl_params.nil?
    end

verify() click to toggle source

returns whether verify_mode is enable from `POP3.ssl_params`

    # File lib/net/pop.rb, line 372
    def POP3.verify
      return @ssl_params[:verify_mode]
    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 436
    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 687
    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

Disable SSL for all new instances.

    # File lib/net/pop.rb, line 463
    def disable_ssl
      @ssl_params = 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 665
    def each_mail(&block)  # :yield: message
      mails().each(&block)
    end

Also aliased as: each
Net::POP#enable_ssl(params = {}) click to toggle source

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.

    # File lib/net/pop.rb, line 452
    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

finish() click to toggle source

Finishes a `POP3` session and closes TCP connection.

    # File lib/net/pop.rb, line 586
    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 468
    def inspect
      +"#<#{self.class} #{@address}:#{@port} open=#{@started}>"
    end

logging(msg) click to toggle source

debugging output for `msg`

    # File lib/net/pop.rb, line 712
    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 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

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 631
    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 624
    def n_mails
      return @n_mails if @n_mails
      @n_mails, @n_bytes = command().stat
      @n_mails
    end

port() click to toggle source

The port number to connect to.

    # File lib/net/pop.rb, line 493
    def port
      return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
    end

read_timeout=(sec) click to toggle source

`Set` the read timeout.

    # File lib/net/pop.rb, line 508
    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 697
    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 485
    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 526
    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 514
    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 441
    def use_ssl?
      return !@ssl_params.nil?
    end