Class: Net::POP3
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)
-
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.
Direct Known Subclasses
Constant Summary collapse
- Revision =
svn revision of this library
%q$Revision: 53141 $.split[1]
Instance Attribute Summary collapse
-
#address ⇒ Object
readonly
The address to connect to.
-
#open_timeout ⇒ Object
Seconds to wait until a connection is opened.
-
#read_timeout ⇒ Object
Seconds to wait until reading one block (by one read(1) call).
Class Method Summary collapse
-
.APOP(isapop) ⇒ Object
Returns the APOP class if
isapop
is true; otherwise, returns the POP class. -
.auth_only(address, port = nil, account = nil, password = nil, isapop = false) ⇒ Object
Opens a POP3 session, attempts authentication, and quits.
-
.certs ⇒ Object
returns the :ca_file or :ca_path from POP3.ssl_params.
-
.create_ssl_params(verify_or_params = {}, certs = nil) ⇒ Object
Constructs proper parameters from arguments.
-
.default_pop3_port ⇒ Object
The default port for POP3 connections, port 110.
-
.default_pop3s_port ⇒ Object
The default port for POP3S connections, port 995.
-
.default_port ⇒ Object
returns the port for POP3.
-
.delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block) ⇒ Object
Starts a POP3 session and deletes all messages on the server.
-
.disable_ssl ⇒ Object
Disable SSL for all new instances.
-
.enable_ssl(*args) ⇒ Object
:call-seq: Net::POP.enable_ssl(params = {}).
-
.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
. -
.socket_type ⇒ Object
:nodoc: obsolete.
-
.ssl_params ⇒ Object
returns the SSL Parameters.
-
.start(address, port = nil, account = nil, password = nil, isapop = false, &block) ⇒ Object
Creates a new POP3 object and open the connection.
-
.use_ssl? ⇒ Boolean
returns
true
if POP3.ssl_params is set. -
.verify ⇒ Object
returns whether verify_mode is enable from POP3.ssl_params.
Instance Method Summary collapse
-
#apop? ⇒ Boolean
Does this instance use APOP authentication?.
-
#auth_only(account, password) ⇒ Object
Starts a pop3 session, attempts authentication, and quits.
-
#delete_all ⇒ Object
Deletes all messages on the server.
-
#disable_ssl ⇒ Object
Disable SSL for all new instances.
-
#each_mail(&block) ⇒ Object
(also: #each)
Yields each message to the passed-in block in turn.
-
#enable_ssl(verify_or_params = {}, certs = nil, port = nil) ⇒ Object
:call-seq: Net::POP#enable_ssl(params = {}).
-
#finish ⇒ Object
Finishes a POP3 session and closes TCP connection.
-
#initialize(addr, port = nil, isapop = false) ⇒ POP3
constructor
Creates a new POP3 object.
-
#inspect ⇒ Object
Provide human-readable stringification of class state.
-
#logging(msg) ⇒ Object
debugging output for
msg
. -
#mails ⇒ Object
Returns an array of Net::POPMail objects, representing all the messages on the server.
-
#n_bytes ⇒ Object
Returns the total size in bytes of all the messages on the POP server.
-
#n_mails ⇒ Object
Returns the number of messages on the POP server.
-
#port ⇒ Object
The port number to connect to.
-
#reset ⇒ Object
Resets the session.
-
#set_all_uids ⇒ Object
:nodoc: internal use only (called from POPMail#uidl).
-
#set_debug_output(arg) ⇒ Object
WARNING: This method causes a serious security hole.
-
#start(account, password) ⇒ Object
Starts a POP3 session.
-
#started? ⇒ Boolean
(also: #active?)
true
if the POP3 session has started. -
#use_ssl? ⇒ Boolean
does this instance use SSL?.
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.
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 |
# 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 |
Instance Attribute Details
#address ⇒ Object (readonly)
The address to connect to.
491 492 493 |
# File 'lib/net/pop.rb', line 491 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.
501 502 503 |
# File 'lib/net/pop.rb', line 501 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.
506 507 508 |
# File 'lib/net/pop.rb', line 506 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
239 240 241 |
# 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) ⇒ 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)
306 307 308 309 310 |
# File 'lib/net/pop.rb', line 306 def POP3.auth_only(address, port = nil, account = nil, password = nil, isapop = false) new(address, port, isapop).auth_only account, password end |
.certs ⇒ Object
returns the :ca_file or :ca_path from POP3.ssl_params
378 379 380 |
# 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) ⇒ Object
Constructs proper parameters from arguments
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 |
# 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 ⇒ Object
The default port for POP3 connections, port 110
211 212 213 |
# File 'lib/net/pop.rb', line 211 def POP3.default_pop3_port 110 end |
.default_pop3s_port ⇒ Object
The default port for POP3S connections, port 995
216 217 218 |
# File 'lib/net/pop.rb', line 216 def POP3.default_pop3s_port 995 end |
.default_port ⇒ Object
returns the port for POP3
206 207 208 |
# 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) ⇒ 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
284 285 286 287 288 289 290 |
# File 'lib/net/pop.rb', line 284 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 |
.disable_ssl ⇒ Object
Disable SSL for all new instances.
356 357 358 |
# File 'lib/net/pop.rb', line 356 def POP3.disable_ssl @ssl_params = nil end |
.enable_ssl(*args) ⇒ Object
333 334 335 |
# 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) ⇒ 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
263 264 265 266 267 268 269 |
# File 'lib/net/pop.rb', line 263 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 |
.socket_type ⇒ Object
:nodoc: obsolete
220 221 222 |
# File 'lib/net/pop.rb', line 220 def POP3.socket_type #:nodoc: obsolete Net::InternetMessageIO end |
.ssl_params ⇒ Object
returns the SSL Parameters
see also POP3.enable_ssl
363 364 365 |
# 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) ⇒ Object
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
402 403 404 405 406 |
# File 'lib/net/pop.rb', line 402 def POP3.start(address, port = nil, account = nil, password = nil, isapop = false, &block) # :yield: pop new(address, port, isapop).start(account, password, &block) end |
.use_ssl? ⇒ Boolean
returns true
if POP3.ssl_params is set
368 369 370 |
# File 'lib/net/pop.rb', line 368 def POP3.use_ssl? return !@ssl_params.nil? end |
.verify ⇒ Object
returns whether verify_mode is enable from POP3.ssl_params
373 374 375 |
# File 'lib/net/pop.rb', line 373 def POP3.verify return @ssl_params[:verify_mode] end |
Instance Method Details
#apop? ⇒ Boolean
Does this instance use APOP authentication?
437 438 439 |
# File 'lib/net/pop.rb', line 437 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.
315 316 317 318 319 320 |
# File 'lib/net/pop.rb', line 315 def auth_only(account, password) raise IOError, 'opening previously opened POP session' if started? start(account, 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.
464 465 466 |
# File 'lib/net/pop.rb', line 464 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
453 454 455 456 457 458 459 460 461 |
# 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 ⇒ Object
Finishes a POP3 session and closes TCP connection.
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.
469 470 471 |
# File 'lib/net/pop.rb', line 469 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.
494 495 496 |
# File 'lib/net/pop.rb', line 494 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
486 487 488 |
# File 'lib/net/pop.rb', line 486 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.
527 528 529 530 531 532 533 534 535 536 537 538 539 540 |
# File 'lib/net/pop.rb', line 527 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? ⇒ Boolean Also known as: active?
true
if the POP3 session has started.
515 516 517 |
# File 'lib/net/pop.rb', line 515 def started? @started end |
#use_ssl? ⇒ Boolean
does this instance use SSL?
442 443 444 |
# File 'lib/net/pop.rb', line 442 def use_ssl? return !@ssl_params.nil? end |