Net::POP3 (Class)

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   command   default_port   delete_all   delete_all   each   each_mail   finish   foreach   inspect   mails   n_bytes   n_mails   new   read_timeout=   reset   set_debug_output   start   start   started?  

Constants

Revision = %q$Revision: 1.62.2.3 $.split[1]
POP = POP3
  class aliases
POPSession = POP3
POP3Session = POP3
APOPSession = APOP
  class aliases

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.

Classes and Modules

Class Net::POP3::APOP
Class Net::POP3::POPMail

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 223
    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 290
    def POP3.auth_only( address, port = nil,
                        account = nil, password = nil,
                        isapop = false )
      new(address, port, isapop).auth_only account, password
    end
default_port()

The default port for POP3 connections, port 110

[Source]

# File net/pop.rb, line 200
    def POP3.default_port
      110
    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 268
    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
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 247
    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; it defaults to 110.

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 342
    def initialize( addr, port = nil, isapop = false )
      @address = addr
      @port = port || self.class.default_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
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 326
    def POP3.start( address, port = nil,
                    account = nil, password = nil,
                    isapop = false, &block ) # :yield: pop

      new(address, port, isapop).start(account, password, &block)
    end

Public Instance methods

active?()

Alias for started?

apop?()

Does this instance use APOP authentication?

[Source]

# File net/pop.rb, line 360
    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 299
    def auth_only( account, password )
      raise IOError, 'opening previously opened POP session' if started?
      start(account, password) {
        ;
      }
    end
command()

[Source]

# File net/pop.rb, line 474
    def command
      raise IOError, 'POP session not opened yet' \
                                      if not @socket or @socket.closed?
      @command
    end
    private :command

    #

    # POP protocol wrapper

    #


    # Returns the number of messages on the POP server.

    def n_mails
      return @n_mails if @n_mails
      @n_mails, @n_bytes = command().stat
      @n_mails
    end

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

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

    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

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

    def each_mail( &block )  # :yield: message

      mails().each(&block)
    end

    alias each each_mail

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

    #

    def delete_all # :yield: message

      mails().each do |m|
        yield m if block_given?
        m.delete unless m.deleted?
      end
    end

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

    #

    # This method raises a POPError if an error occurs.

    def reset
      command().rset
      mails().each do |m|
        m.instance_eval {
          @deleted = false
        }
      end
    end

    def set_all_uids   #:nodoc: internal use only (called from POPMail#uidl)

      command().uidl.each do |num, uid|
        @mails.find {|m| m.number == num }.uid = uid
      end
    end

  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 549
    def delete_all # :yield: message

      mails().each do |m|
        yield m if block_given?
        m.delete unless m.deleted?
      end
    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 527
    def each_mail( &block )  # :yield: message

      mails().each(&block)
    end
finish()

Finishes a POP3 session and closes TCP connection.

[Source]

# File net/pop.rb, line 458
    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 365
    def inspect
      "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
    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 505
    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 493
    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 486
    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 403
    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 559
    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 382
    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 421
    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 409
    def started?
      @started
    end

[Validate]