Inheritance: < Net::Protocol < Object

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)

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

Name		Description
Revision	= %q$Revision: 16193 $.split[1]

Attributes

Name	Visibility	R/W	Description
address	public	R	The address to connect to.
open_timeout	public	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.
read_timeout	public	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.

Methods

Class

Visibility	Signature
public	APOP (isapop)
public	auth_only (address, port = nil, account = nil, password = nil, isapop = false)
public	certs ()
public	create_ssl_params (verify_or_params = {}, certs = nil)
public	default_pop3_port ()
public	default_pop3s_port ()
public	default_port ()
public	delete_all (address, port = nil, account = nil, password = nil, isapop = false, &block)
public	disable_ssl ()
public	enable_ssl (*args)
public	foreach (address, port = nil, account = nil, password = nil, isapop = false) {\|message\| ...}
public	new (addr, port = nil, isapop = false)
public	ssl_params ()
public	start (address, port = nil, account = nil, password = nil, isapop = false) {\|pop\| ...}
public	use_ssl? ()
public	verify ()

Instance

Visibility	Signature
public	active? ()
public	apop? ()
public	auth_only (account, password)
public	delete_all ( {\|message\| ...}
public	disable_ssl ()
public	each ()
public	each_mail () {\|message\| ...}
public	enable_ssl (verify_or_params = {}, certs = nil, port = nil)
public	finish ()
public	inspect ()
public	logging (msg)
public	mails ()
public	n_bytes ()
public	n_mails ()
public	port ()
public	read_timeout= (sec)
public	reset ()
public	set_debug_output (arg)
public	start (account, password) {\|pop\| ...}
public	started? ()
public	use_ssl? ()

Class Method Detail

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

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)

certs()

create_ssl_params(verify_or_params = {}, certs = nil)

default_pop3_port()

The default port for POP3 connections, port 110

default_pop3s_port()

The default port for POP3S connections, port 995

default_port()

Class Parameters

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

disable_ssl()

Disable SSL for all new instances.

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

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

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)

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

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

use_ssl?()

verify()

Instance Method Detail

active?()

Alias for started?

apop?()

Does this instance use APOP authentication?

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.

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.

disable_ssl()

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.

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

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

Finishes a POP3 session and closes TCP connection.

inspect()

Provide human-readable stringification of class state.

logging(msg)

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.

n_bytes()

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

n_mails()

Returns the number of messages on the POP server.

port()

The port number to connect to.

read_timeout=(sec)

Set the read timeout.

reset()

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

This method raises a POPError if an error occurs.

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

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.

started?()

true if the POP3 session has started.

use_ssl?()

does this instance use SSL?