Class: Mail::IMAP

Inherits:
Retriever show all
Defined in:
lib/mail/network/retriever_methods/imap.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Retriever

#all, #find_and_delete, #first, #last

Constructor Details

#initialize(values) ⇒ IMAP

Returns a new instance of IMAP.



38
39
40
41
42
43
44
45
 
# File 'lib/mail/network/retriever_methods/imap.rb', line 38

def initialize(values)
  self.settings = { :address              => "localhost",
                    :port                 => 110,
                    :user_name            => nil,
                    :password             => nil,
                    :authentication       => nil,
                    :enable_ssl           => false }.merge!(values)
end

Instance Attribute Details

#settings ⇒ Object

Returns the value of attribute settings.



47
48
49
 
# File 'lib/mail/network/retriever_methods/imap.rb', line 47

def settings
  @settings
end

Instance Method Details

#connection(&block) ⇒ Object

Returns the connection object of the retrievable (IMAP or POP3)

Raises:

  • (ArgumentError) 


113
114
115
116
117
118
119
 
# File 'lib/mail/network/retriever_methods/imap.rb', line 113

def connection(&block)
  raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?

  start do |imap|
    yield imap
  end
end

#delete_all(mailbox = 'INBOX') ⇒ Object

Delete all emails from a IMAP mailbox



99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/mail/network/retriever_methods/imap.rb', line 99

def delete_all(mailbox='INBOX')
  mailbox ||= 'INBOX'
  mailbox = Net::IMAP.encode_utf7(mailbox)

  start do |imap|
    imap.select(mailbox)
    imap.uid_search(['ALL']).each do |message_id|
      imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED])
    end
    imap.expunge
  end
end

#find(options = {}, &block) ⇒ Object

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.
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.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/mail/network/retriever_methods/imap.rb', line 60

def find(options={}, &block)
  options = validate_options(options)

  start do |imap|
    imap.select(options[:mailbox])

    message_ids = imap.uid_search(options[:keys])
    message_ids.reverse! if options[:what].to_sym == :last
    message_ids = message_ids.first(options[:count]) if options[:count].is_a?(Integer)
    message_ids.reverse! if (options[:what].to_sym == :last && options[:order].to_sym == :asc) ||
                            (options[:what].to_sym != :last && options[:order].to_sym == :desc)

    if block_given?
      message_ids.each do |message_id|
        fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
        new_message = Mail.new(fetchdata.attr['RFC822'])
        new_message.mark_for_delete = true if options[:delete_after_find]
        if block.arity == 3
          yield new_message, imap, message_id
        else
          yield new_message
        end
        imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] && new_message.is_marked_for_delete?
      end
      imap.expunge if options[:delete_after_find]
    else
      emails = []
      message_ids.each do |message_id|
        fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
        emails << Mail.new(fetchdata.attr['RFC822'])
        imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find]
      end
      imap.expunge if options[:delete_after_find]
      emails.size == 1 && options[:count] == 1 ? emails.first : emails
    end
  end
end