Net::POPSession

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 Net::POP3#each_mail and/or Net::POP3#mails.
Close POP session by calling Net::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 Net::POP3.new, Net::POP3#start and Net::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

Net::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 Net::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

Revision

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 ) 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 net/pop.rb, line 223
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 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() click to toggle source

The default port for POP3 connections, port 110

 
               # File net/pop.rb, line 200
def POP3.default_port
  110
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 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 ) 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 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 ) 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; 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.

 
               # 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 ) 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 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?() click to toggle source

Alias for: started?

apop?() click to toggle source

Does this instance use APOP authentication?

 
               # File net/pop.rb, line 360
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 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() 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 net/pop.rb, line 551
def delete_all # :yield: message
  mails().each do |m|
    yield m if block_given?
    m.delete unless m.deleted?
  end
end

each( ) click to toggle source

Alias for: each_mail

each_mail( ) 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 net/pop.rb, line 529
def each_mail( &block )  # :yield: message
  mails().each(&block)
end

Also aliased as: each

finish() click to toggle source

Finishes a POP3 session and closes TCP connection.

 
               # File net/pop.rb, line 458
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 net/pop.rb, line 365
def inspect
  "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
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 net/pop.rb, line 507
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 net/pop.rb, line 495
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 net/pop.rb, line 488
def n_mails
  return @n_mails if @n_mails
  @n_mails, @n_bytes = command().stat
  @n_mails
end

read_timeout=( sec ) click to toggle source

Set the read timeout.

 
               # File net/pop.rb, line 403
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 net/pop.rb, line 561
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 net/pop.rb, line 382
def set_debug_output( arg )
  @debug_output = arg
end

start( account, password ) 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 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?() click to toggle source

true if the POP3 session has started.

 
               # File net/pop.rb, line 409
def started?
  @started
end

Also aliased as: active?

Home Classes Methods

In Files

Parent

Methods

Class/Module Index

Net::POPSession

Net::POP3¶ ↑

What is This Library?¶ ↑

Examples¶ ↑

Retrieving Messages ¶ ↑

Shortened Code¶ ↑

Memory Space Issues¶ ↑

Using APOP¶ ↑

Fetch Only Selected Mail Using 'UIDL' POP Command¶ ↑

Constants

Attributes

Public Class Methods

Example: normal POP3¶ ↑

Example: APOP¶ ↑

Example¶ ↑

Example¶ ↑

Example¶ ↑

Public Instance Methods

Example¶ ↑

Example¶ ↑