Class: Net::POP3

Inherits:
Protocol show all
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 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($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.

Direct Known Subclasses

APOP

Constant Summary collapse

VERSION =

version of this library

"0.1.1"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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



417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'lib/net/pop.rb', line 417

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

Instance Attribute Details

#address ⇒ Object (readonly)

The address to connect to.



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

def address
  @address
end

#open_timeout ⇒ Object

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.



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

def open_timeout
  @open_timeout
end

#read_timeout ⇒ Object

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.



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

def read_timeout
  @read_timeout
end

Class Method Details

.APOP(isapop) ⇒ Object

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



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

def POP3.APOP(isapop)
  isapop ? APOP : POP3
end

.auth_only(address, port = nil, account = nil, password = nil, isapop = false) ⇒ Object

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)



305
306
307
308
309
 
# File 'lib/net/pop.rb', line 305

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

.certs ⇒ Object

returns the :ca_file or :ca_path from POP3.ssl_params



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

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

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

Constructs proper parameters from arguments



337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/net/pop.rb', line 337

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 ⇒ Object

The default port for POP3 connections, port 110



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

def POP3.default_pop3_port
  110
end

.default_pop3s_port ⇒ Object

The default port for POP3S connections, port 995



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

def POP3.default_pop3s_port
  995
end

.default_port ⇒ Object

returns the port for POP3



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

def POP3.default_port
  default_pop3_port()
end

.delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block) ⇒ Object

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



283
284
285
286
287
288
289
 
# File 'lib/net/pop.rb', line 283

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 ⇒ Object

Disable SSL for all new instances.



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

def POP3.disable_ssl
  @ssl_params = nil
end

.enable_ssl(*args) ⇒ Object

:call-seq:

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

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



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

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

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

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



262
263
264
265
266
267
268
 
# File 'lib/net/pop.rb', line 262

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 ⇒ Object

:nodoc: obsolete



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

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

.ssl_params ⇒ Object

returns the SSL Parameters

see also POP3.enable_ssl



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

def POP3.ssl_params
  return @ssl_params
end

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

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



401
402
403
404
405
 
# File 'lib/net/pop.rb', line 401

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

.use_ssl? ⇒ Boolean

returns true if POP3.ssl_params is set

Returns:

  • (Boolean) 


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

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

.verify ⇒ Object

returns whether verify_mode is enable from POP3.ssl_params



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

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

Instance Method Details

#apop? ⇒ Boolean

Does this instance use APOP authentication?

Returns:

  • (Boolean) 


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

def apop?
  @apop
end

#auth_only(account, password) ⇒ Object

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) 


314
315
316
317
318
319
 
# File 'lib/net/pop.rb', line 314

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

#delete_all ⇒ Object

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.



687
688
689
690
691
692
 
# 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 ⇒ Object

Disable SSL for all new instances.



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

def disable_ssl
  @ssl_params = nil
end

#each_mail(&block) ⇒ Object 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.



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

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

#enable_ssl(verify_or_params = {}, certs = nil, port = nil) ⇒ Object

:call-seq:

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.



452
453
454
455
456
457
458
459
460
 
# File 'lib/net/pop.rb', line 452

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 ⇒ Object

Finishes a POP3 session and closes TCP connection.

Raises:

  • (IOError) 


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

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

#inspect ⇒ Object

Provide human-readable stringification of class state.



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

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

#logging(msg) ⇒ Object

debugging output for msg



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

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

#mails ⇒ Object

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.



643
644
645
646
647
648
649
650
651
652
653
654
655
 
# 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 ⇒ Object

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



631
632
633
634
635
 
# 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 ⇒ Object

Returns the number of messages on the POP server.



624
625
626
627
628
 
# 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

#port ⇒ Object

The port number to connect to.



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

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

#reset ⇒ Object

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

This method raises a POPError if an error occurs.



697
698
699
700
701
702
703
704
 
# 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 ⇒ Object

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



706
707
708
709
 
# 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) ⇒ Object

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



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

def set_debug_output(arg)
  @debug_output = arg
end

#start(account, password) ⇒ Object

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) 


526
527
528
529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/net/pop.rb', line 526

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

#started? ⇒ Boolean Also known as: active?

true if the POP3 session has started.

Returns:

  • (Boolean) 


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

def started?
  @started
end

#use_ssl? ⇒ Boolean

does this instance use SSL?

Returns:

  • (Boolean) 


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

def use_ssl?
  return !@ssl_params.nil?
end