The IMAP retriever allows to get the last, first or all emails from a IMAP 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 => 143, 41: :user_name => nil, 42: :password => nil, 43: :authentication => nil, 44: :enable_ssl => false }.merge!(values) 45: end
Returns the connection object of the retrievable (IMAP or POP3)
# File lib/mail/network/retriever_methods/imap.rb, line 114 114: def connection(&block) 115: raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given? 116: 117: start do |imap| 118: yield imap 119: end 120: end
Delete all emails from a IMAP mailbox
# File lib/mail/network/retriever_methods/imap.rb, line 101 101: def delete_all(mailbox='INBOX') 102: mailbox ||= 'INBOX' 103: mailbox = Net::IMAP.encode_utf7(mailbox) 104: 105: start do |imap| 106: imap.uid_search(['ALL']).each do |message_id| 107: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) 108: end 109: imap.expunge 110: end 111: end
Find emails in a IMAP 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. ready_only: will ensure that no writes are made to the inbox during the session. This is helpful when you don't want your messages to be set to read automatically. Default is false. delete_after_find: flag for whether to delete each retreived email after find. Default is false. Use #find_and_delete if you would like this to default to true.
# File lib/mail/network/retriever_methods/imap.rb, line 62 62: def find(options={}, &block) 63: options = validate_options(options) 64: 65: start do |imap| 66: options[:read_only] ? imap.select(options[:mailbox]) : imap.examine(options[:mailbox]) 67: 68: message_ids = imap.uid_search(options[:keys]) 69: message_ids.reverse! if options[:what].to_sym == :last 70: message_ids = message_ids.first(options[:count]) if options[:count].is_a?(Integer) 71: message_ids.reverse! if (options[:what].to_sym == :last && options[:order].to_sym == :asc) || 72: (options[:what].to_sym != :last && options[:order].to_sym == :desc) 73: 74: if block_given? 75: message_ids.each do |message_id| 76: fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0] 77: new_message = Mail.new(fetchdata.attr['RFC822']) 78: new_message.mark_for_delete = true if options[:delete_after_find] 79: if block.arity == 3 80: yield new_message, imap, message_id 81: else 82: yield new_message 83: end 84: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] && new_message.is_marked_for_delete? 85: end 86: imap.expunge if options[:delete_after_find] 87: else 88: emails = [] 89: message_ids.each do |message_id| 90: fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0] 91: emails << Mail.new(fetchdata.attr['RFC822']) 92: imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] 93: end 94: imap.expunge if options[:delete_after_find] 95: emails.size == 1 && options[:count] == 1 ? emails.first : emails 96: end 97: end 98: end
Start an IMAP session and ensures that it will be closed in any case.
# File lib/mail/network/retriever_methods/imap.rb, line 140 140: def start(config=Mail::Configuration.instance, &block) 141: raise ArgumentError.new("Mail::Retrievable#imap_start takes a block") unless block_given? 142: 143: imap = Net::IMAP.new(settings[:address], settings[:port], settings[:enable_ssl], nil, false) 144: if settings[:authentication].nil? 145: imap.login(settings[:user_name], settings[:password]) 146: else 147: # Note that Net::IMAP#authenticate('LOGIN', ...) is not equal with Net::IMAP#login(...)! 148: # (see also http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/imap/rdoc/classes/Net/IMAP.html#M000718) 149: imap.authenticate(settings[:authentication], settings[:user_name], settings[:password]) 150: end 151: 152: yield imap 153: ensure 154: if defined?(imap) && imap && !imap.disconnected? 155: imap.disconnect 156: end 157: end
Set default options
# File lib/mail/network/retriever_methods/imap.rb, line 125 125: def validate_options(options) 126: options ||= {} 127: options[:mailbox] ||= 'INBOX' 128: options[:count] ||= 10 129: options[:order] ||= :asc 130: options[:what] ||= :first 131: options[:keys] ||= 'ALL' 132: options[:delete_after_find] ||= false 133: options[:mailbox] = Net::IMAP.encode_utf7(options[:mailbox]) 134: options[:read_only] ||= false 135: 136: options 137: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.