Class: Net::POP3

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

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]