Object
The IMAP retriever allows to get the last, first or all emails from a POP3 server. Each email retrieved (RFC2822) is given as an instance of Message.
While being retrieved, emails can be yielded if a block is given.
Mail.defaults do retriever_method :imap, { :address => "imap.googlemail.com", :port => 993, :user_name => '<username>', :password => '<password>', :enable_ssl => true } end Mail.all #=> Returns an array of all emails Mail.first #=> Returns the first unread email Mail.last #=> Returns the first unread email
You can also pass options into Mail.find to locate an email in your imap mailbox with the following options:
mailbox: name of the mailbox used for email retrieval. The default is 'INBOX'. what: last or first emails. The default is :first. order: order of emails returned. Possible values are :asc or :desc. Default value is :asc. count: number of emails to retrieve. The default value is 10. A value of 1 returns an instance of Message, not an array of Message instances. Mail.find(:what => :first, :count => 10, :order => :asc) #=> Returns the first 10 emails in ascending order
# File lib/mail/network/retriever_methods/imap.rb, line 38 38: def initialize(values) 39: self.settings = { :address => "localhost", 40: :port => 110, 41: :user_name => nil, 42: :password => nil, 43: :authentication => nil, 44: :enable_ssl => false }.merge!(values) 45: end
Get all emails.
Possible options:
mailbox: mailbox to retrieve all email(s) from. The default is 'INBOX'. count: number of emails to retrieve. The default value is 1. order: order of emails returned. Possible values are :asc or :desc. Default value is :asc. keys: keywords for the imap SEARCH command. Can be either a string holding the entire search string or a single-dimension array of search keywords and arguments.
# File lib/mail/network/retriever_methods/imap.rb, line 90 90: def all(options={}, &block) 91: options ||= {} 92: options[:count] = :all 93: options[:keys] = 'ALL' 94: find(options, &block) 95: end
Returns the connection object of the retrievable (IMAP or POP3)
# File lib/mail/network/retriever_methods/imap.rb, line 155 155: def connection(&block) 156: raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given? 157: 158: start do |imap| 159: yield imap 160: end 161: end
Delete all emails from a IMAP mailbox
# File lib/mail/network/retriever_methods/imap.rb, line 141 141: def delete_all(mailbox='INBOX') 142: mailbox ||= 'INBOX' 143: mailbox = Net::IMAP.encode_utf7(mailbox) 144: 145: start do |imap| 146: imap.select(mailbox) 147: imap.uid_search(['ALL']).each do |message_id| 148: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) 149: end 150: imap.expunge 151: end 152: end
Find emails in a POP3 mailbox. Without any options, the 10 last received emails are returned.
Possible options:
mailbox: mailbox to search the email(s) in. The default is 'INBOX'. what: last or first emails. The default is :first. order: order of emails returned. Possible values are :asc or :desc. Default value is :asc. count: number of emails to retrieve. The default value is 10. A value of 1 returns an instance of Message, not an array of Message instances.
# File lib/mail/network/retriever_methods/imap.rb, line 106 106: def find(options={}, &block) 107: options = validate_options(options) 108: 109: start do |imap| 110: imap.select(options[:mailbox]) 111: 112: message_ids = imap.uid_search(options[:keys]) 113: message_ids.reverse! if options[:what].to_sym == :last 114: message_ids = message_ids.first(options[:count]) if options[:count].is_a?(Integer) 115: message_ids.reverse! if (options[:what].to_sym == :last && options[:order].to_sym == :asc) || 116: (options[:what].to_sym != :last && options[:order].to_sym == :desc) 117: 118: if block_given? 119: message_ids.each do |message_id| 120: fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0] 121: new_message = Mail.new(fetchdata.attr['RFC822']) 122: new_message.mark_for_delete = true if options[:delete_after_find] 123: yield new_message 124: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] && new_message.is_marked_for_delete? 125: end 126: imap.expunge if options[:delete_after_find] 127: else 128: emails = [] 129: message_ids.each do |message_id| 130: fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0] 131: emails << Mail.new(fetchdata.attr['RFC822']) 132: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] 133: end 134: imap.expunge if options[:delete_after_find] 135: emails.size == 1 && options[:count] == 1 ? emails.first : emails 136: end 137: end 138: end
Get the oldest received email(s)
Possible options:
mailbox: mailbox to retrieve the oldest received email(s) from. The default is 'INBOX'. count: number of emails to retrieve. The default value is 1. order: order of emails returned. Possible values are :asc or :desc. Default value is :asc. keys: keywords for the imap SEARCH command. Can be either a string holding the entire search string or a single-dimension array of search keywords and arguments.
# File lib/mail/network/retriever_methods/imap.rb, line 58 58: def first(options={}, &block) 59: options ||= {} 60: options[:what] = :first 61: options[:count] ||= 1 62: find(options, &block) 63: end
Get the most recent received email(s)
Possible options:
mailbox: mailbox to retrieve the most recent received email(s) from. The default is 'INBOX'. count: number of emails to retrieve. The default value is 1. order: order of emails returned. Possible values are :asc or :desc. Default value is :asc. keys: keywords for the imap SEARCH command. Can be either a string holding the entire search string or a single-dimension array of search keywords and arguments.
# File lib/mail/network/retriever_methods/imap.rb, line 74 74: def last(options={}, &block) 75: options ||= {} 76: options[:what] = :last 77: options[:count] ||= 1 78: find(options, &block) 79: end
Start an IMAP session and ensures that it will be closed in any case.
# File lib/mail/network/retriever_methods/imap.rb, line 180 180: def start(config=Mail::Configuration.instance, &block) 181: raise ArgumentError.new("Mail::Retrievable#imap_start takes a block") unless block_given? 182: 183: imap = Net::IMAP.new(settings[:address], settings[:port], settings[:enable_ssl], nil, false) 184: imap.login(settings[:user_name], settings[:password]) 185: 186: yield imap 187: ensure 188: if defined?(imap) && imap && !imap.disconnected? 189: imap.disconnect 190: end 191: end
Set default options
# File lib/mail/network/retriever_methods/imap.rb, line 166 166: def validate_options(options) 167: options ||= {} 168: options[:mailbox] ||= 'INBOX' 169: options[:count] ||= 10 170: options[:order] ||= :asc 171: options[:what] ||= :first 172: options[:keys] ||= 'ALL' 173: options[:delete_after_find] ||= false 174: options[:mailbox] = Net::IMAP.encode_utf7(options[:mailbox]) 175: 176: options 177: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.