класс Net::IMAP

# File lib/net/imap.rb, line 898
def add_response_handler(handler = Proc.new)
  @response_handlers.push(handler)
end

Добавляет обработчик ответов. Например, чтобы обнаружить, когда сервер отправляет новый ответ EXISTS (который обычно указывает на добавление новых сообщений в почтовый ящик), добавьте следующий обработчик после выбора почтового ящика:

imap.add_response_handler { |resp|
  if resp.kind_of?(Net::IMAP::UntaggedResponse) and resp.name == "EXISTS"
    puts "Mailbox now has #{resp.data} messages"
  end
}

# File lib/net/imap.rb, line 691
def append(mailbox, message, flags = nil, date_time = nil)
  args = []
  if flags
    args.push(flags)
  end
  args.push(date_time) if date_time
  args.push(Literal.new(message))
  send_command("APPEND", mailbox, *args)
end

Отправляет команду APPEND, чтобы добавить message в конец mailbox. Необязательный аргумент flags представляет собой массив флагов, первоначально переданных новому сообщению. Необязательный аргумент date_time указывает время создания, которое нужно назначить новому сообщению; по умолчанию используется текущее время. Например:

imap.append("inbox", "Subject: hello
From: shugo@ruby-lang.org
To: shugo@ruby-lang.org

hello world
".gsub(/\n/, "\r\n"), [:Seen], Time.now)

Возникает исключение Net::IMAP::NoResponseError, если почтовый ящик не существует (он не создается автоматически) или если аргументы flags, date_time или message содержат ошибки.

# File lib/net/imap.rb, line 409
def authenticate(auth_type, *args)
  auth_type = auth_type.upcase
  unless @@authenticators.has_key?(auth_type)
    raise ArgumentError,
      format('unknown auth type - "%s"', auth_type)
  end
  authenticator = @@authenticators[auth_type].new(*args)
  send_command("AUTHENTICATE", auth_type) do |resp|
    if resp.instance_of?(ContinuationRequest)
      data = authenticator.process(resp.data.text.unpack("m")[0])
      s = [data].pack("m0")
      send_string_data(s)
      put_string(CRLF)
    end
  end
end

Отправляет команду AUTHENTICATE для аутентификации клиента. Параметр auth_type — это строка, представляющая используемый механизм аутентификации. В настоящее время Net::IMAP поддерживает механизмы аутентификации:

LOGIN:: login using cleartext user and password.
CRAM-MD5:: login with cleartext user and encrypted password
           (see [RFC-2195] for a full description).  This
           mechanism requires that the server have the user's
           password stored in clear-text password.

Для обоих этих механизмов должно быть два args: имя пользователя и (открытый) пароль. Сервер может не поддерживать один или другой из этих механизмов; проверьте capability() для возможности в форме «AUTH=LOGIN» или «AUTH=CRAM-MD5».

Аутентификация выполняется с использованием соответствующего объекта аутентификатора: см. @@authenticators для получения дополнительной информации о подключении собственного аутентификатора.

Например:

imap.authenticate('LOGIN', user, password)

Возникает исключение Net::IMAP::NoResponseError, если аутентификация не удалась.

# File lib/net/imap.rb, line 351
def capability
  synchronize do
    send_command("CAPABILITY")
    return @responses.delete("CAPABILITY")[-1]
  end
end

Отправляет команду CAPABILITY и возвращает массив возможностей, поддерживаемых сервером. Каждая возможность — это строка. См. [IMAP] для списка возможных возможностей.

Обратите внимание, что класс Net::IMAP не изменяет свое поведение в соответствии с возможностями сервера; пользователь класса должен убедиться, что определенная возможность поддерживается сервером, прежде чем использовать ее.

# File lib/net/imap.rb, line 705
def check
  send_command("CHECK")
end

Отправляет команду CHECK для запроса контрольной точки текущего выбранного почтового ящика. Это выполняет специфичные для реализации действия по обслуживанию; например, согласование состояния почтового ящика в памяти и на диске.

# File lib/net/imap.rb, line 712
def close
  send_command("CLOSE")
end

Отправляет команду CLOSE для закрытия текущего выбранного почтового ящика. Команда CLOSE окончательно удаляет из почтового ящика все сообщения, для которых установлен флаг Deleted.

# File lib/net/imap.rb, line 845
def copy(set, mailbox)
  copy_internal("COPY", set, mailbox)
end

Отправляет команду COPY для копирования указанного сообщения (сообщений) в конец указанного почтового ящика назначения mailbox. Параметр set — это число, массив чисел или объект Range. Число — это порядковый номер сообщения.

# File lib/net/imap.rb, line 472
def create(mailbox)
  send_command("CREATE", mailbox)
end

Отправляет команду CREATE для создания нового mailbox.

Возникает исключение Net::IMAP::NoResponseError, если почтовый ящик с таким именем не может быть создан.

# File lib/net/imap.rb, line 481
def delete(mailbox)
  send_command("DELETE", mailbox)
end

Отправляет команду DELETE для удаления mailbox.

Возникает исключение Net::IMAP::NoResponseError, если почтовый ящик с таким именем не может быть удален, либо потому что он не существует, либо потому что клиент не имеет права его удалять.

# File lib/net/imap.rb, line 315
def disconnect
  begin
    begin
      # try to call SSL::SSLSocket#io.
      @sock.io.shutdown
    rescue NoMethodError
      # @sock is not an SSL::SSLSocket.
      @sock.shutdown
    end
  rescue Errno::ENOTCONN
    # ignore `Errno::ENOTCONN: Socket is not connected' on some platforms.
  rescue Exception => e
    @receiver_thread.raise(e)
  end
  @receiver_thread.join
  synchronize do
    @sock.close
  end
  raise e if e
end

Отключается от сервера.

# File lib/net/imap.rb, line 337
def disconnected?
  return @sock.closed?
end

Возвращает true, если отключен от сервера.

# File lib/net/imap.rb, line 461
def examine(mailbox)
  synchronize do
    @responses.clear
    send_command("EXAMINE", mailbox)
  end
end

Отправляет команду EXAMINE для выбора mailbox, чтобы можно было получить доступ к сообщениям в mailbox. Ведет себя так же, как select(), за исключением того, что выбранный mailbox идентифицируется как доступный только для чтения.

Возникает исключение Net::IMAP::NoResponseError, если почтовый ящик не существует или по какой-либо причине недоступен для проверки.

# File lib/net/imap.rb, line 718
def expunge
  synchronize do
    send_command("EXPUNGE")
    return @responses.delete("EXPUNGE")
  end
end

Отправляет команду EXPUNGE для окончательного удаления из текущего выбранного почтового ящика всех сообщений, для которых установлен флаг Deleted.

# File lib/net/imap.rb, line 809
def fetch(set, attr)
  return fetch_internal("FETCH", set, attr)
end

Отправляет команду FETCH для извлечения данных, связанных с сообщением в почтовом ящике.

Параметр set — это число или диапазон между двумя числами или массив из них. Число — это порядковый номер сообщения, где -1 представляет собой '*' для использования в обозначении диапазона, например, 100..-1 интерпретируется как '100:*'. Имейте в виду, что свойство exclude_end? объекта Range игнорируется, а содержимое диапазона не зависит от порядка конечных точек диапазона в соответствии со спецификацией протокола, поэтому 1…5, 5..1 и 5…1 эквивалентны 1..5.

attr — это список атрибутов для извлечения; см. документацию для Net::IMAP::FetchData для списка допустимых атрибутов.

Возвращаемое значение — это массив Net::IMAP::FetchData или nil (вместо пустого массива), если нет совпадающих сообщений.

Например:

p imap.fetch(6..8, "UID")
#=> [#<Net::IMAP::FetchData seqno=6, attr={"UID"=>98}>, \\
     #<Net::IMAP::FetchData seqno=7, attr={"UID"=>99}>, \\
     #<Net::IMAP::FetchData seqno=8, attr={"UID"=>100}>]
p imap.fetch(6, "BODY[HEADER.FIELDS (SUBJECT)]")
#=> [#<Net::IMAP::FetchData seqno=6, attr={"BODY[HEADER.FIELDS (SUBJECT)]"=>"Subject: test\r\n\r\n"}>]
data = imap.uid_fetch(98, ["RFC822.SIZE", "INTERNALDATE"])[0]
p data.seqno
#=> 6
p data.attr["RFC822.SIZE"]
#=> 611
p data.attr["INTERNALDATE"]
#=> "12-Oct-2000 22:40:59 +0900"
p data.attr["UID"]
#=> 98

# File lib/net/imap.rb, line 631
def getacl(mailbox)
  synchronize do
    send_command("GETACL", mailbox)
    return @responses.delete("ACL")[-1]
  end
end

Отправляет команду GETACL вместе с указанным mailbox. Если этот почтовый ящик существует, возвращается массив, содержащий объекты Net::IMAP::MailboxACLItem.

# File lib/net/imap.rb, line 595
def getquota(mailbox)
  synchronize do
    send_command("GETQUOTA", mailbox)
    return @responses.delete("QUOTA")
  end
end

Отправляет команду GETQUOTA вместе с указанным mailbox. Если этот почтовый ящик существует, то возвращается массив, содержащий объект Net::IMAP::MailboxQuota. Эта команда обычно доступна только администратору сервера.

# File lib/net/imap.rb, line 581
def getquotaroot(mailbox)
  synchronize do
    send_command("GETQUOTAROOT", mailbox)
    result = []
    result.concat(@responses.delete("QUOTAROOT"))
    result.concat(@responses.delete("QUOTA"))
    return result
  end
end

Отправляет команду GETQUOTAROOT вместе с указанным mailbox. Эта команда обычно доступна как администраторам, так и пользователям. Если почтовый ящик существует, возвращает массив, содержащий объекты типа Net::IMAP::MailboxQuotaRoot и Net::IMAP::MailboxQuota.

# File lib/net/imap.rb, line 944
def idle(timeout = nil, &response_handler)
  raise LocalJumpError, "no block given" unless response_handler

  response = nil

  synchronize do
    tag = Thread.current[:net_imap_tag] = generate_tag
    put_string("#{tag} IDLE#{CRLF}")

    begin
      add_response_handler(response_handler)
      @idle_done_cond = new_cond
      @idle_done_cond.wait(timeout)
      @idle_done_cond = nil
      if @receiver_thread_terminating
        raise Net::IMAP::Error, "connection closed"
      end
    ensure
      unless @receiver_thread_terminating
        remove_response_handler(response_handler)
        put_string("DONE#{CRLF}")
        response = get_tagged_response(tag, "IDLE")
      end
    end
  end

  return response
end

Отправляет команду IDLE, которая ожидает уведомлений о новых или удаленных сообщениях. Во время ожидания IDLE выводит ответы от сервера.

Для выхода из режима IDLE используйте idle_done().

Если задан timeout, этот метод возвращает результат после истечения timeout секунд. timeout может использоваться для поддержания соединения. Например, следующий код проверяет соединение каждые 60 секунд.

loop do
  imap.idle(60) do |res|
    ...
  end
end

# File lib/net/imap.rb, line 974
def idle_done
  synchronize do
    if @idle_done_cond.nil?
      raise Net::IMAP::Error, "not during IDLE"
    end
    @idle_done_cond.signal
  end
end

Выходит из режима IDLE.

# File lib/net/imap.rb, line 538
def list(refname, mailbox)
  synchronize do
    send_command("LIST", refname, mailbox)
    return @responses.delete("LIST")
  end
end

Отправляет команду LIST и возвращает подмножество имён из полного набора доступных клиенту имён. refname предоставляет контекст (например, базовую директорию в иерархии почтовых ящиков на основе каталогов). mailbox указывает почтовый ящик или (с помощью подстановочных знаков) почтовые ящики в этом контексте. В mailbox могут использоваться два подстановочных знака: '*' — соответствует всем символам, включая разделитель иерархии (например, '/' в иерархии почтовых ящиков на основе каталогов на UNIX-системах); и '%' — соответствует всем символам, кроме разделителя иерархии.

Если refname пусто, mailbox используется непосредственно для определения, какие почтовые ящики подходят. Если mailbox пусто, возвращаются корневое имя refname и разделитель иерархии.

Возвращаемое значение — массив Net::IMAP::MailboxList. Например:

imap.create("foo/bar")
imap.create("foo/baz")
p imap.list("", "foo/%")
#=> [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]

# File lib/net/imap.rb, line 432
def login(user, password)
  send_command("LOGIN", user, password)
end

Отправляет команду LOGIN для идентификации клиента и содержит открытый текст password для аутентификации этого user. Обратите внимание, что в отличие от вызова authenticate() с auth_type «LOGIN», login() не использует аутентификатор входа.

Если аутентификация не удалась, генерируется Net::IMAP::NoResponseError.

# File lib/net/imap.rb, line 365
def logout
  send_command("LOGOUT")
end

Отправляет команду LOGOUT, чтобы сообщить серверу, что клиент закончил работу с подключением.

# File lib/net/imap.rb, line 643
def lsub(refname, mailbox)
  synchronize do
    send_command("LSUB", refname, mailbox)
    return @responses.delete("LSUB")
  end
end

Отправляет команду LSUB и возвращает подмножество имён из набора имён, которые пользователь объявил как «активные» или «подписанные». refname и mailbox интерпретируются так же, как и для list(). Возвращаемое значение — массив Net::IMAP::MailboxList.

# File lib/net/imap.rb, line 859
def move(set, mailbox)
  copy_internal("MOVE", set, mailbox)
end

Отправляет команду MOVE для перемещения указанных сообщений в конец указанного целевого mailbox. Параметр set — число, массив чисел или объект Range. Число — порядковый номер сообщения. Расширение MOVE для IMAP описано в [RFC-6851].

# File lib/net/imap.rb, line 359
def noop
  send_command("NOOP")
end

Отправляет команду NOOP на сервер. Ничего не делает.

# File lib/net/imap.rb, line 903
def remove_response_handler(handler)
  @response_handlers.delete(handler)
end

Удаляет обработчик ответов.

# File lib/net/imap.rb, line 492
def rename(mailbox, newname)
  send_command("RENAME", mailbox, newname)
end

Отправляет команду RENAME для изменения имени mailbox на newname.

Если почтовый ящик с именем mailbox не может быть переименован в newname по какой-либо причине (например, потому что mailbox не существует или потому, что уже существует почтовый ящик с именем newname), генерируется Net::IMAP::NoResponseError.

# File lib/net/imap.rb, line 765
def search(keys, charset = nil)
  return search_internal("SEARCH", keys, charset)
end

Отправляет команду SEARCH для поиска сообщений в почтовом ящике, соответствующих заданным критериям поиска, и возвращает порядковые номера сообщений. keys может быть строкой, содержащей всю строку поиска, или одномерным массивом ключевых слов и аргументов поиска. Ниже приведены некоторые распространённые критерии поиска; см. раздел [IMAP] 6.4.4 для полного списка.

<набор сообщений>

набор порядковых номеров сообщений. ',' указывает интервал, ':' — диапазон. Например, '2,10:12,15' означает «2,10,11,12,15».

BEFORE <дата>

сообщения с внутренней датой строго до <дата>. Аргумент даты имеет формат, аналогичный 8-авг-2002.

BODY <строка>

сообщения, содержащие <строка> в своём теле.

CC <строка>

сообщения, содержащие <строка> в поле CC.

FROM <строка>

сообщения, содержащие <строка> в поле FROM.

NEW

сообщения с установленным флагом Recent, но не Seen.

NOT <ключ поиска>

отменить следующий ключ поиска.

OR <ключ поиска> <ключ поиска>

соединить два ключа поиска оператором «или».

ON <дата>

сообщения с внутренней датой, точно равной <дата>, имеющей формат, аналогичный 8-авг-2002.

SINCE <дата>

сообщения с внутренней датой на или после <дата>.

SUBJECT <строка>

сообщения с <строкой> в теме.

TO <строка>

сообщения с <строкой> в поле TO.

Например:

p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
#=> [1, 6, 7, 8]

# File lib/net/imap.rb, line 448
def select(mailbox)
  synchronize do
    @responses.clear
    send_command("SELECT", mailbox)
  end
end

Отправляет команду SELECT для выбора mailbox, чтобы можно было получить доступ к сообщениям в mailbox.

После выбора почтового ящика вы можете получить количество элементов в этом почтовом ящике из @responses[-1], а количество новых сообщений — из @responses[-1]. Обратите внимание, что эти значения могут измениться, если во время сессии появятся новые сообщения; см. add_response_handler(), чтобы узнать, как обнаружить это событие.

Если почтовый ящик не существует или по какой-либо причине не может быть выбран, генерируется Net::IMAP::NoResponseError.

# File lib/net/imap.rb, line 620
def setacl(mailbox, user, rights)
  if rights.nil?
    send_command("SETACL", mailbox, user, "")
  else
    send_command("SETACL", mailbox, user, rights)
  end
end

Отправляет команду SETACL вместе с mailbox, user и rights, которые пользователь должен иметь для этого почтового ящика. Если rights равно nil, права этого пользователя для этого почтового ящика будут удалены. Команды ACL IMAP описаны в [RFC-2086].

# File lib/net/imap.rb, line 607
def setquota(mailbox, quota)
  if quota.nil?
    data = '()'
  else
    data = '(STORAGE ' + quota.to_s + ')'
  end
  send_command("SETQUOTA", mailbox, RawData.new(data))
end

Отправляет команду SETQUOTA вместе с указанными mailbox и quota. Если quota равно nil, то quota будет сброшено для этого почтового ящика. Как правило, для этого необходимо войти в систему как администратор сервера. Команды квот IMAP описаны в [RFC-2087].

# File lib/net/imap.rb, line 877
def sort(sort_keys, search_keys, charset)
  return sort_internal("SORT", sort_keys, search_keys, charset)
end

Отправляет команду SORT для сортировки сообщений в почтовом ящике. Возвращает массив номеров последовательности сообщений. Например:

p imap.sort(["FROM"], ["ALL"], "US-ASCII")
#=> [1, 2, 3, 5, 6, 7, 8, 4, 9]
p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
#=> [6, 7, 8, 1]

См. [SORT-THREAD-EXT] для получения более подробной информации.

# File lib/net/imap.rb, line 370
def starttls(options = {}, verify = true)
  send_command("STARTTLS") do |resp|
    if resp.kind_of?(TaggedResponse) && resp.name == "OK"
      begin
        # for backward compatibility
        certs = options.to_str
        options = create_ssl_params(certs, verify)
      rescue NoMethodError
      end
      start_tls_session(options)
    end
  end
end

Отправляет команду STARTTLS для запуска сеанса TLS.

# File lib/net/imap.rb, line 666
def status(mailbox, attr)
  synchronize do
    send_command("STATUS", mailbox, attr)
    return @responses.delete("STATUS")[-1].attr
  end
end

Отправляет команду STATUS и возвращает состояние указанного mailbox. attr — это список одного или нескольких атрибутов, состояния которых необходимо запросить. Поддерживаемые атрибуты включают в себя:

MESSAGES:: the number of messages in the mailbox.
RECENT:: the number of recent messages in the mailbox.
UNSEEN:: the number of unseen messages in the mailbox.

Возвращаемое значение — это хэш атрибутов. Например:

p imap.status("inbox", ["MESSAGES", "RECENT"])
#=> {"RECENT"=>0, "MESSAGES"=>44}

Исключение Net::IMAP::NoResponseError возникает, если значения состояния для mailbox не могут быть возвращены; например, потому что он не существует.

# File lib/net/imap.rb, line 832
def store(set, attr, flags)
  return store_internal("STORE", set, attr, flags)
end

Отправляет команду STORE для изменения данных, связанных с сообщениями в почтовом ящике, в частности, их флагов. Параметр set представляет собой число, массив чисел или объект Range. Каждое число — это номер последовательности сообщений. attr — это имя элемента данных для хранения: 'FLAGS' заменит список флагов сообщения предоставленным, '+FLAGS' добавит предоставленные флаги, а '-FLAGS' удалит их. flags — это список флагов.

Возвращаемое значение — это массив Net::IMAP::FetchData. Например:

p imap.store(6..8, "+FLAGS", [:Deleted])
#=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
     #<Net::IMAP::FetchData seqno=7, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
     #<Net::IMAP::FetchData seqno=8, attr={"FLAGS"=>[:Seen, :Deleted]}>]

# File lib/net/imap.rb, line 502
def subscribe(mailbox)
  send_command("SUBSCRIBE", mailbox)
end

Отправляет команду SUBSCRIBE, чтобы добавить указанное имя mailbox в набор «активных» или «подписанных» почтовых ящиков сервера, возвращаемых функцией lsub().

Исключение Net::IMAP::NoResponseError возникает, если невозможно подписаться на mailbox; например, потому что он не существует.

# File lib/net/imap.rb, line 920
def thread(algorithm, search_keys, charset)
  return thread_internal("THREAD", algorithm, search_keys, charset)
end

Аналогично search(), но возвращает номера последовательности сообщений в формате потока, как дерево Net::IMAP::ThreadMember. Поддерживаемые алгоритмы:

ORDEREDSUBJECT

разделение на одноуровневые потоки в соответствии с темой, упорядоченные по дате.

REFERENCES

разделение на потоки по отношениям родитель/потомок, определяемым тем, какое сообщение является ответом на какое.

В отличие от search(), charset является обязательным аргументом. US-ASCII и UTF-8 являются примерами значений.

См. [SORT-THREAD-EXT] для получения более подробной информации.

# File lib/net/imap.rb, line 850
def uid_copy(set, mailbox)
  copy_internal("UID COPY", set, mailbox)
end

Аналогично copy(), но set содержит уникальные идентификаторы.

# File lib/net/imap.rb, line 814
def uid_fetch(set, attr)
  return fetch_internal("UID FETCH", set, attr)
end

Аналогично fetch(), но set содержит уникальные идентификаторы.

# File lib/net/imap.rb, line 864
def uid_move(set, mailbox)
  copy_internal("UID MOVE", set, mailbox)
end

Аналогично move(), но set содержит уникальные идентификаторы.

# File lib/net/imap.rb, line 770
def uid_search(keys, charset = nil)
  return search_internal("UID SEARCH", keys, charset)
end

Аналогично search(), но возвращает уникальные идентификаторы.

# File lib/net/imap.rb, line 882
def uid_sort(sort_keys, search_keys, charset)
  return sort_internal("UID SORT", sort_keys, search_keys, charset)
end

Аналогично sort(), но возвращает массив уникальных идентификаторов.

# File lib/net/imap.rb, line 837
def uid_store(set, attr, flags)
  return store_internal("UID STORE", set, attr, flags)
end

Аналогично store(), но set содержит уникальные идентификаторы.

# File lib/net/imap.rb, line 926
def uid_thread(algorithm, search_keys, charset)
  return thread_internal("UID THREAD", algorithm, search_keys, charset)
end

Аналогично thread(), но возвращает уникальные идентификаторы вместо номеров последовательности сообщений.

# File lib/net/imap.rb, line 512
def unsubscribe(mailbox)
  send_command("UNSUBSCRIBE", mailbox)
end

Отправляет команду UNSUBSCRIBE, чтобы удалить указанное имя mailbox из набора «активных» или «подписанных» почтовых ящиков сервера.

Исключение Net::IMAP::NoResponseError возникает, если невозможно отписаться от mailbox; например, потому что клиент в настоящее время не подписан на него.

# File lib/net/imap.rb, line 570
def xlist(refname, mailbox)
  synchronize do
    send_command("XLIST", refname, mailbox)
    return @responses.delete("XLIST")
  end
end

Отправляет команду XLIST и возвращает подмножество имен из полного набора всех имен, доступных клиенту. refname предоставляет контекст (например, базовый каталог в иерархии почтовых ящиков на основе каталогов). mailbox указывает почтовый ящик или (с помощью подстановочных знаков) почтовые ящики в этом контексте. В mailbox можно использовать два подстановочных знака: '*', который соответствует всем символам включая разделитель иерархии (например, '/' в иерархии почтовых ящиков на основе каталогов, размещенных на UNIX); и '%', который соответствует всем символам кроме разделителя иерархии.

Если refname пуст, mailbox используется непосредственно для определения почтовых ящиков, с которыми нужно сопоставлять. Если mailbox пуст, возвращаются корневое имя refname и разделитель иерархии.

Команда XLIST похожа на команду LIST, за исключением того, что возвращаемые флаги относятся к функции папки/почтового ящика, например: :Sent

Возвращаемое значение — это массив Net::IMAP::MailboxList. Например:

imap.create("foo/bar")
imap.create("foo/baz")
p imap.xlist("", "foo/%")
#=> [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]