Parent

Object

Class Index [+]

Quicksearch

Mail::IMAP

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.

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                 => 110,
41:                         :user_name            => nil,
42:                         :password             => nil,
43:                         :authentication       => nil,
44:                         :enable_ssl           => false }.merge!(values)
45:     end

Public Instance Methods

all(options={}, &block) click to toggle source

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

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

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

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

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

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

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.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.