123456789_123456789_123456789_123456789_123456789_

Class: Net::POP3

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
APOP
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Protocol
Instance Chain:
self, Protocol
Inherits: Protocol
  • Object
Defined in: lib/net/pop.rb

Overview

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 #start and start POP session.

  2. Access messages by using #each_mail and/or #mails.

  3. Close POP session by calling #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 .start can be used instead of .new, #start and #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

#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 APOP class instead of the POP3 class. You can use the utility method, POP3.APOP(). For example:

require 'net/pop'

# Use APOP authentication if $isapop == true
pop = Net::POP3.APOP($isapop).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.

Constant Summary

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(addr, port = nil, isapop = false) ⇒ POP3

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.

[ GitHub ] 

  


# File 'lib/net/pop.rb', line 418



def initialize(addr, port = nil, isapop = false)
  @address = addr
  @ssl_params = POP3.ssl_params
  @port = 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


  







Class Attribute Details



  

    .use_ssl?  ⇒ Boolean  (readonly)
  



  

    

returns true if .ssl_params is set


  





  


  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 368



def POP3.use_ssl?
  return !@ssl_params.nil?
end


  







Class Method Details



  

    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


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 239



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)


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 306



def POP3.auth_only(address, port = nil,
                    = nil, password = nil,
                   isapop = false)
  new(address, port, isapop).auth_only , password
end


  








  

    .certs  
  



  

    

returns the :ca_file or :ca_path from .ssl_params


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 378



def POP3.certs
  return @ssl_params[:ca_file] || @ssl_params[:ca_path]
end


  








  

    .create_ssl_params(verify_or_params = {}, certs = nil)  
  



  

    

Constructs proper parameters from arguments


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 338



def POP3.create_ssl_params(verify_or_params = {}, certs = nil)
  begin
    params = verify_or_params.to_hash
  rescue NoMethodError
    params = {}
    params[:verify_mode] = verify_or_params
    if certs
      if File.file?(certs)
        params[:ca_file] = certs
      elsif File.directory?(certs)
        params[:ca_path] = certs
      end
    end
  end
  return params
end


  








  

    .default_pop3_port  
  



  

    

The default port for POP3 connections, port 110


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 211



def POP3.default_pop3_port
  110
end


  








  

    .default_pop3s_port  
  



  

    

The default port for POP3S connections, port 995


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 216



def POP3.default_pop3s_port
  995
end


  








  

    .default_port  
  



  

    

returns the port for POP3


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 206



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


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 284



def POP3.delete_all(address, port = nil,
                     = nil, password = nil,
                    isapop = false, &block)
  start(address, port, , password, isapop) {|pop|
    pop.delete_all(&block)
  }
end


  








  

    .disable_ssl  
  



  

    

Disable SSL for all new instances.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 356



def POP3.disable_ssl
  @ssl_params = nil
end


  








  

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



  

    

Enable SSL for all new instances. params is passed to OpenSSL::SSLContext#set_params.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 333



def POP3.enable_ssl(*args)
  @ssl_params = create_ssl_params(*args)
end


  








  

    .foreach(address, port = nil, account = nil, password = nil, isapop = false, &block)  
  



  

    

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, , 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


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 263



def POP3.foreach(address, port = nil,
                  = nil, password = nil,
                 isapop = false, &block)  # :yields: message
  start(address, port, , password, isapop) {|pop|
    pop.each_mail(&block)
  }
end


  








  

    .socket_type  
  

  

    This method is for internal use only.
  



  

    

obsolete


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 220



def POP3.socket_type   #:nodoc: obsolete
  Net::InternetMessageIO
end


  








  

    .ssl_params  
  



  

    

returns the SSL Parameters



see also .enable_ssl


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 363



def POP3.ssl_params
  return @ssl_params
end


  








  

    .start(address, port = nil, account = nil, password = nil, isapop = false, &block)  
  



  

    

Creates a new POP3 object and open the connection.  Equivalent to



Net::POP3.new(address, port, isapop).start(, 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, , password) do |pop|
  pop.each_mail do |m|
    file.write m.pop
    m.delete
  end
end


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 402



def POP3.start(address, port = nil,
                = nil, password = nil,
               isapop = false, &block)   # :yield: pop
  new(address, port, isapop).start(, password, &block)
end


  








  

    .verify  
  



  

    

returns whether verify_mode is enable from .ssl_params


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 373



def POP3.verify
  return @ssl_params[:verify_mode]
end


  







Instance Attribute Details



  

    #active?   (readonly)
  

  

    This method is for internal use only.
  



  

    

Alias for #started?.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 519



alias active? started?   #:nodoc: obsolete


  








  

    #address   (readonly)
  



  

    

The address to connect to.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 491



attr_reader :address


  








  

    #apop?  ⇒ Boolean  (readonly)
  



  

    

Does this instance use .APOP authentication?


  





  


  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 437



def apop?
  @apop
end


  








  

    #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 Net::OpenTimeout exception. The default value is 30 seconds.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 501



attr_accessor :open_timeout


  








  

    #read_timeout   (rw)
  



  

    

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 Net::ReadTimeout exception. The default value is 60 seconds.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 506



attr_reader :read_timeout


  








  

    #read_timeout=(sec)   (rw)
  



  

    

Set the read timeout.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 509



def read_timeout=(sec)
  @command.socket.read_timeout = sec if @command
  @read_timeout = sec
end


  








  

    #started?  ⇒ Boolean  (readonly)
    Also known as: #active?
  



  

    

true if the POP3 session has started.


  





  


  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 515



def started?
  @started
end


  








  

    #use_ssl?  ⇒ Boolean  (readonly)
  



  

    

does this instance use SSL?


  





  


  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 442



def use_ssl?
  return !@ssl_params.nil?
end


  







Instance Method Details



  

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


  





  
Raises:


    
  
  • 
    (IOError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 315



def auth_only(, password)
  raise IOError, 'opening previously opened POP session' if started?
  start(, password) {
    ;
  }
end


  








  

    #command   (private)
  

  

    This method is for internal use only.
  



  

    

Returns the current command.



Raises IOError if there is no active socket


  





  
Raises:


    
  
  • 
    (IOError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 612



def command # :nodoc:
  raise IOError, 'POP session not opened yet' \
                                  if not @socket or @socket.closed?
  @command
end


  








  

    #delete_all  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 687



def delete_all # :yield: message
  mails().each do |m|
    yield m if block_given?
    m.delete unless m.deleted?
  end
end


  








  

    #disable_ssl  
  



  

    

Disable SSL for all new instances.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 464



def disable_ssl
  @ssl_params = nil
end


  








  

    #do_finish   (private)
  

  

    This method is for internal use only.
  



  

    

nil’s out the:


  • 

    mails
    

  • 

    number counter for mails
    

  • 

    number counter for bytes
    

  • 

    quits the current command, if any
    



  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 596



def do_finish # :nodoc:
  @mails = nil
  @n_mails = nil
  @n_bytes = nil
  @command.quit if @command
ensure
  @started = false
  @command = nil
  @socket.close if @socket
  @socket = nil
end


  








  

    #do_start(account, password)   (private)
  

  

    This method is for internal use only.
  



  

    

internal method for .start


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 543



def do_start(, password) # :nodoc:
  s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
    TCPSocket.open(@address, port)
  end
  if use_ssl?
    raise 'openssl library not installed' unless defined?(OpenSSL)
    context = OpenSSL::SSL::SSLContext.new
    context.set_params(@ssl_params)
    s = OpenSSL::SSL::SSLSocket.new(s, context)
    s.sync_close = true
    ssl_socket_connect(s, @open_timeout)
    if context.verify_mode != OpenSSL::SSL::VERIFY_NONE
      s.post_connection_check(@address)
    end
  end
  @socket = InternetMessageIO.new(s,
                                  read_timeout: @read_timeout,
                                  debug_output: @debug_output)
  logging "POP session started: #{@address}:#{@port} (#{@apop ? 'APOP' : 'POP'})"
  on_connect
  @command = POP3Command.new(@socket)
  if apop?
    @command.apop , password
  else
    @command.auth , password
  end
  @started = true
ensure
  # Authentication failed, clean up connection.
  unless @started
    s.close if s
    @socket = nil
    @command = nil
  end
end


  








  

    #each(&block)  
  



  

    

Alias for #each_mail.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 669



alias each each_mail


  








  

    #each_mail(&block)  
    Also known as: #each
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 665



def each_mail(&block)  # :yield: message
  mails().each(&block)
end


  








  

    Net::POP    



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 453



def enable_ssl(verify_or_params = {}, certs = nil, port = nil)
  begin
    @ssl_params = verify_or_params.to_hash.dup
    @port = @ssl_params.delete(:port) || @port
  rescue NoMethodError
    @ssl_params = POP3.create_ssl_params(verify_or_params, certs)
    @port = port || @port
  end
end


  








  

    #finish  
  



  

    

Finishes a POP3 session and closes TCP connection.


  





  
Raises:


    
  
  • 
    (IOError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 586



def finish
  raise IOError, 'POP session not yet started' unless started?
  do_finish
end


  








  

    #inspect  
  



  

    

Provide human-readable stringification of class state.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 469



def inspect
  +"#<#{self.class} #{@address}:#{@port} open=#{@started}>"
end


  








  

    #logging(msg)  
  



  

    

debugging output for msg


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 712



def logging(msg)
  @debug_output << msg + "\n" if @debug_output
end


  








  

    #mails  
  



  

    

Returns an array of 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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 643



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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 631



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.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 624



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


  








  

    #on_connect   (private)
  

  

    This method is for internal use only.
  



  

    

Does nothing


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 581



def on_connect # :nodoc:
end


  








  

    #port  
  



  

    

The port number to connect to.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 494



def port
  return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
end


  








  

    #reset  
  



  

    

Resets the session.  This clears all “deleted” marks from messages.



This method raises a POPError if an error occurs.


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 697



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


  








  

    #set_all_uids  
  

  

    This method is for internal use only.
  



  

    

internal use only (called from POPMail#uidl)


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 706



def set_all_uids   #:nodoc: internal use only (called from POPMail#uidl)
  uidl = command().uidl
  @mails.each {|m| m.uid = uidl[m.number] }
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(, passwd) do |pop|
  #....
end


  



  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 486



def set_debug_output(arg)
  @debug_output = arg
end


  








  

    #start(account, password)  
  



  

    

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.


  





  
Raises:


    
  
  • 
    (IOError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/net/pop.rb', line 527



def start(, password) # :yield: pop
  raise IOError, 'POP session already started' if @started
  if block_given?
    begin
      do_start , password
      return yield(self)
    ensure
      do_finish
    end
  else
    do_start , password
    return self
  end
end