Class Index [+]

Quicksearch

Mail::IMAP

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.

Example of retrieving Emails from GMail:

  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

Attributes

settings[RW]

Public Class Methods

new(values) click to toggle source
    # 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

Public Instance Methods

connection(&block) click to toggle source

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(mailbox='INBOX') click to toggle source

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(options={}, &block) click to toggle source

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

Private Instance Methods

start(config=Mail::Configuration.instance, &block) click to toggle source

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
validate_options(options) click to toggle source

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.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.