Class Net::POP3
In: net/pop.rb
Parent: Protocol

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.

Methods

APOP   active?   apop?   auth_only   auth_only   certs   default_pop3_port   default_pop3s_port   default_port   delete_all   delete_all   disable_ssl   disable_ssl   each   each_mail   enable_ssl   enable_ssl   finish   foreach   inspect   logging   mails   n_bytes   n_mails   new   read_timeout=   reset   set_debug_output   start   start   started?   use_ssl?   use_ssl?   verify  

Constants

Revision = %q$Revision: 1.73 $.split[1]

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)

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

[Source]

# File net/pop.rb, line 238
    def POP3.APOP(isapop)
      isapop ? APOP : POP3
    end
auth_only(address, port = nil, account = nil, password = nil, isapop = false)

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)

[Source]

# 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
certs()

[Source]

# File net/pop.rb, line 355
    def POP3.certs
      @certs
    end
default_pop3_port()

The default port for POP3 connections, port 110

[Source]

# File net/pop.rb, line 210
    def POP3.default_pop3_port
      110
    end
default_pop3s_port()

The default port for POP3S connections, port 995

[Source]

# File net/pop.rb, line 215
    def POP3.default_pop3s_port
      995
    end
default_port()

Class Parameters

[Source]

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

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

[Source]

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

Disable SSL for all new instances.

[Source]

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

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.

[Source]

# File 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| ...}

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

[Source]

# 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
new(addr, port = nil, isapop = false)

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.

[Source]

# File 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| ...}

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

[Source]

# File 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?()

[Source]

# File net/pop.rb, line 347
    def POP3.use_ssl?
      @use_ssl
    end
verify()

[Source]

# File net/pop.rb, line 351
    def POP3.verify
      @verify
    end

Public Instance methods

active?()

Alias for started?

apop?()

Does this instance use APOP authentication?

[Source]

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

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.

[Source]

# File 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| ...}

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.

[Source]

# File 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()

[Source]

# File net/pop.rb, line 440
    def disable_ssl
      @use_ssl = false
      @verify = nil
      @certs = nil
    end
each()

Alias for each_mail

each_mail() {|message| ...}

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.

[Source]

# File net/pop.rb, line 633
    def each_mail(&block)  # :yield: message
      mails().each(&block)
    end
enable_ssl(verify = OpenSSL::SSL::VERIFY_PEER, certs = nil, port = POP3.default_pop3s_port)

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.

[Source]

# File 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()

Finishes a POP3 session and closes TCP connection.

[Source]

# File net/pop.rb, line 564
    def finish
      raise IOError, 'POP session not yet started' unless started?
      do_finish
    end
inspect()

Provide human-readable stringification of class state.

[Source]

# File net/pop.rb, line 447
    def inspect
      "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
    end
logging(msg)

[Source]

# File net/pop.rb, line 680
    def logging(msg)
      @debug_output << msg + "\n" if @debug_output
    end
mails()

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.

[Source]

# File 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()

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

[Source]

# File 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()

Returns the number of messages on the POP server.

[Source]

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

Set the read timeout.

[Source]

# File net/pop.rb, line 485
    def read_timeout=(sec)
      @command.socket.read_timeout = sec if @command
      @read_timeout = sec
    end
reset()

Resets the session. This clears all "deleted" marks from messages.

This method raises a POPError if an error occurs.

[Source]

# File net/pop.rb, line 665
    def reset
      command().rset
      mails().each do |m|
        m.instance_eval {
          @deleted = false
        }
      end
    end
set_debug_output(arg)

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

[Source]

# File net/pop.rb, line 464
    def set_debug_output(arg)
      @debug_output = arg
    end
start(account, password) {|pop| ...}

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.

[Source]

# File 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?()

true if the POP3 session has started.

[Source]

# File net/pop.rb, line 491
    def started?
      @started
    end
use_ssl?()

does this instance use SSL?

[Source]

# File net/pop.rb, line 421
    def use_ssl?
      @use_ssl
    end
To view or add comments on this documentation, please go to the API wiki.

[Validate]