Class: Net::IMAP

Sets the debug mode.

Decodes string as an IMAP4 formatted “date-time”.

Note that double quotes are not optional. See STRFTIME.

Decodes string as an IMAP4 formatted “date-time”.

Same as .decode_datetime, but returning a Time instead.

Decode a string from modified UTF-7 format to UTF-8.

UTF-7 is a 7-bit encoding of Unicode [UTF7]. IMAP uses a slightly modified version of this to encode mailbox names containing non-ASCII characters; see [IMAP] section 5.1.3.

IMAP does not automatically encode and decode mailbox names to and from UTF-7.

Alias for .default_port.

Alias for .default_tls_port.

The default port for IMAP connections, port 143

Alias for .default_tls_port.

The default port for IMAPS connections, port 993

Formats time as an IMAP4 date.

Formats time as an IMAP4 date-time.

Alias for .encode_datetime.

Encode a string from UTF-8 format to modified UTF-7.

Alias for .encode_date.

DEPRECATED

The original version returned incorrectly formatted strings. Strings returned by encode_datetime or format_time use the correct IMAP4rev1 syntax for “date-time”.

This invalid format has been temporarily retained for backward compatibility. A future release will change this method to return the correct format.

Alias for .encode_time.

Alias for .decode_date.

Alias for .decode_datetime.

Alias for .decode_time.

Returns true if disconnected from the server.

Related: #logout, #disconnect

Returns the initial greeting the server, an IMAP::UntaggedResponse.

Seconds to wait until an IDLE response is received.

Seconds to wait until a connection is opened. If the IMAP object cannot open a connection within this time, it raises a Net::OpenTimeout exception. The default value is 30 seconds.

Returns all response handlers.

Returns recorded untagged responses.

For example:

imap.select("inbox")
p imap.responses["EXISTS"][-1]
#=> 2
p imap.responses["UIDVALIDITY"][-1]
#=> 968263756

Sends an APPEND command [IMAP4rev1 §6.3.11] to append the message to the end of the mailbox. The optional flags argument is an array of flags initially passed to the new message. The optional date_time argument specifies the creation time to assign to the new message; it defaults to the current time.

For example:

imap.append("inbox", <<EOF.gsub(/\n/, "\r\n"), [:Seen], Time.now)
Subject: hello
From: shugo@ruby-lang.org
To: shugo@ruby-lang.org

hello world
EOF

A IMAP::NoResponseError is raised if the mailbox does not exist (it is not created automatically), or if the flags, date_time, or message arguments contain errors.

Capabilities

If UIDPLUS [RFC4315] is supported and the destination supports persistent UIDs, the server’s response should include an APPENDUID response code with IMAP::UIDPlusData. This will report the UIDVALIDITY of the destination mailbox and the assigned UID of the appended message.

Sends an AUTHENTICATE command [IMAP4rev1 §6.2.2] to authenticate the client. If successful, the connection enters the “authenticated” state.

mechanism is the name of the SASL authentication mechanism to be used. All other arguments are forwarded to the authenticator for the requested mechanism. The listed call signatures are suggestions. The documentation for each individual mechanism must be consulted for its specific parameters.

An exception IMAP::NoResponseError is raised if authentication fails.

Related: #login, #starttls

Supported SASL Mechanisms

PLAIN

See PlainAuthenticator. Login using clear-text username and password.

XOAUTH2

See XOauth2Authenticator. Login using a username and OAuth2 access token. Non-standard and obsoleted by OAUTHBEARER, but widely supported.

Deprecated: Obsolete mechanisms are available for backwards compatibility.

For DIGEST-MD5 see DigestMD5Authenticator.

For LOGIN, see LoginAuthenticator.

For CRAM-MD5, see CramMD5Authenticator.

Using a deprecated mechanism will print a warning.

See IMAP::Authenticators for information on plugging in authenticators for other mechanisms. See the SASL mechanism registry for information on these and other IMAP::SASL mechanisms.

Capabilities

Clients MUST NOT attempt to authenticate with a mechanism unless "AUTH=#{mechanism}" for that mechanism is a server capability.

Server capabilities may change after #starttls, #login, and #authenticate. Cached capabilities must be invalidated after this method completes. The TaggedResponse to #authenticate may include updated capabilities in its IMAP::ResponseCode.

Example

If the authenticators ignore unhandled keyword arguments, the same config can be used for multiple mechanisms:

password  = nil # saved locally, so we don't ask more than once
accesstok = nil # saved locally...
creds = {
  authcid:      username,
  password:     proc { password  ||= ui.prompt_for_password },
  oauth2_token: proc { accesstok ||= kms.fresh_access_token },
}
capa = imap.capability
if    capa.include? "AUTH=OAUTHBEARER"
  imap.authenticate "OAUTHBEARER",   **creds # authcid, oauth2_token
elsif capa.include? "AUTH=XOAUTH2"
  imap.authenticate "XOAUTH2",       **creds # authcid, oauth2_token
elsif capa.include? "AUTH=SCRAM-SHA-256"
  imap.authenticate "SCRAM-SHA-256", **creds # authcid, password
elsif capa.include? "AUTH=PLAIN"
  imap.authenticate "PLAIN",         **creds # authcid, password
elsif capa.include? "AUTH=DIGEST-MD5"
  imap.authenticate "DIGEST-MD5",    **creds # authcid, password
elsif capa.include? "LOGINDISABLED"
  raise "the server has disabled login"
else
  imap.login username, password
end

Sends a CAPABILITY command [IMAP4rev1 §6.1.1] and returns an array of capabilities that the server supports. Each capability is a string.

See the IANA IMAP4 capabilities registry for a list of all standard capabilities, and their reference RFCs.

Note that Net::IMAP does not currently modify its behaviour according to the capabilities of the server; it is up to the user of the class to ensure that a certain capability is supported by a server before using it.

Capability requirements—other than IMAP4rev1—are listed in the documentation for each command method.

Basic IMAP4rev1 capabilities

All IMAP4rev1 servers must include IMAP4rev1 in their capabilities list. All IMAP4rev1 servers must implement the STARTTLS, AUTH=PLAIN, and LOGINDISABLED capabilities, and clients must respect their presence or absence. See the capabilites requirements on #starttls, #login, and #authenticate.

Using IMAP4rev1 extensions

IMAP4rev1 servers must not activate incompatible behavior until an explicit client action invokes a capability, e.g. sending a command or command argument specific to that capability. Extensions with backward compatible behavior, such as response codes or mailbox attributes, may be sent at any time.

Invoking capabilities which are unknown to IMAP may cause unexpected behavior and errors, for example IMAP::ResponseParseError is raised when unknown response syntax is received. Invoking commands or command parameters that are unsupported by the server may raise IMAP::NoResponseError, IMAP::BadResponseError, or cause other unexpected behavior.

Caching CAPABILITY responses

Servers may send their capability list, unsolicited, using the CAPABILITY response code or an untagged CAPABILITY response. These responses can be retrieved and cached using #responses or #add_response_handler.

But cached capabilities must be discarded after #starttls, #login, or #authenticate. The OK IMAP::TaggedResponse to #login and #authenticate may include CAPABILITY response code data, but the IMAP::TaggedResponse for #starttls is sent clear-text and cannot be trusted.

Sends a CHECK command [IMAP4rev1 §6.4.1] to request a checkpoint of the currently selected mailbox. This performs implementation-specific housekeeping; for instance, reconciling the mailbox’s in-memory and on-disk state.

Related: #idle, #noop

Sends a CLOSE command [IMAP4rev1 §6.4.2] to close the currently selected mailbox. The CLOSE command permanently removes from the mailbox all messages that have the \Deleted flag set.

Related: #unselect

Sends a COPY command [IMAP4rev1 §6.4.7] to copy the specified message(s) to the end of the specified destination mailbox. The set parameter is a number, an array of numbers, or a Range object. The number is a message sequence number.

Related: #uid_copy

Capabilities

If UIDPLUS [RFC4315] is supported, the server’s response should include a COPYUID response code with IMAP::UIDPlusData. This will report the UIDVALIDITY of the destination mailbox, the UID set of the source messages, and the assigned UID set of the moved messages.

Sends a CREATE command [IMAP4rev1 §6.3.3] to create a new mailbox.

A IMAP::NoResponseError is raised if a mailbox with that name cannot be created.

Related: #rename, #delete

Sends a DELETE command [IMAP4rev1 §6.3.4] to remove the mailbox.

A IMAP::NoResponseError is raised if a mailbox with that name cannot be deleted, either because it does not exist or because the client does not have permission to delete it.

Related: #create, #rename

Disconnects from the server.

Related: #logout

Sends a EXAMINE command [IMAP4rev1 §6.3.2] to select a mailbox so that messages in the mailbox can be accessed. Behaves the same as #select, except that the selected mailbox is identified as read-only.

A IMAP::NoResponseError is raised if the mailbox does not exist or is for some reason non-examinable.

Related: #select

Sends an EXPUNGE command [IMAP4rev1 §6.4.3] Sends a EXPUNGE command to permanently remove from the currently selected mailbox all messages that have the Deleted flag set.

Related: #uid_expunge

Sends a FETCH command [IMAP4rev1 §6.4.5] to retrieve data associated with a message in the mailbox.

The set parameter is a number or a range between two numbers, or an array of those. The number is a message sequence number, where -1 represents a ‘*’ for use in range notation like 100..-1 being interpreted as ‘100:*’. Beware that the exclude_end? property of a Range object is ignored, and the contents of a range are independent of the order of the range endpoints as per the protocol specification, so 1…5, 5..1 and 5…1 are all equivalent to 1..5.

attr is a list of attributes to fetch; see the documentation for IMAP::FetchData for a list of valid attributes.

The return value is an array of IMAP::FetchData or nil (instead of an empty array) if there is no matching message.

Related: #uid_search, IMAP::FetchData

For example:

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

Sends a GETACL command [RFC4314 §3.3] along with a specified mailbox. If this mailbox exists, an array containing objects of IMAP::MailboxACLItem will be returned.

Related: #setacl, IMAP::MailboxACLItem

Capabilities

The server’s capabilities must include ACL [RFC4314].

Sends a GETQUOTA command [RFC2087 §4.2] along with specified mailbox. If this mailbox exists, then an array containing a IMAP::MailboxQuota object is returned. This command is generally only available to server admin.

Related: #getquotaroot, #setquota, IMAP::MailboxQuota

Capabilities

The server’s capabilities must include QUOTA [RFC2087].

Sends a GETQUOTAROOT command [RFC2087 §4.3] along with the specified mailbox. This command is generally available to both admin and user. If this mailbox exists, it returns an array containing objects of type IMAP::MailboxQuotaRoot and IMAP::MailboxQuota.

Related: #getquota, #setquota, IMAP::MailboxQuotaRoot, IMAP::MailboxQuota

Capabilities

The server’s capabilities must include QUOTA [RFC2087].

Sends an ID command [RFC2971 §3.1] and returns a hash of the server’s response, or nil if the server does not identify itself.

Note that the user should first check if the server supports the ID capability. For example:

capabilities = imap.capability
if capabilities.include?("ID")
  id = imap.id(
    name: "my IMAP client (ruby)",
    version: MyIMAP::VERSION,
    "support-url": "mailto:bugs@example.com",
    os: RbConfig::CONFIG["host_os"],
  )
end

See [ID] for field definitions.

Capabilities

The server’s capabilities must include ID

RFC2971

Sends an IDLE command [RFC2177 §3] [IMAP4rev2 §6.3.13] that waits for notifications of new or expunged messages. Yields responses from the server during the IDLE.

Use #idle_done to leave IDLE.

If timeout is given, this method returns after timeout seconds passed. timeout can be used for keep-alive. For example, the following code checks the connection for each 60 seconds.

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

Related: #idle_done, #noop, #check

Capabilities

The server’s capabilities must include IDLE [RFC2177].

Leaves IDLE.

Related: #idle

Sends a LIST command [IMAP4rev1 §6.3.8] and returns a subset of names from the complete set of all names available to the client. refname provides a context (for instance, a base directory in a directory-based mailbox hierarchy). mailbox specifies a mailbox or (via wildcards) mailboxes under that context. Two wildcards may be used in mailbox: ‘*’, which matches all characters including the hierarchy delimiter (for instance, ‘/’ on a UNIX-hosted directory-based mailbox hierarchy); and ‘%’, which matches all characters except the hierarchy delimiter.

If refname is empty, mailbox is used directly to determine which mailboxes to match. If mailbox is empty, the root name of refname and the hierarchy delimiter are returned.

The return value is an array of IMAP::MailboxList.

Related: #lsub, IMAP::MailboxList

For example:

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">]

Sends a LOGIN command [IMAP4rev1 §6.2.3] to identify the client and carries the plaintext password authenticating this user. If successful, the connection enters the “authenticated” state.

Using #authenticate is generally preferred over #login. The LOGIN command is not the same as #authenticate with the “LOGIN” mechanism.

A IMAP::NoResponseError is raised if authentication fails.

Related: #authenticate, #starttls

Capabilities

Clients MUST NOT call #login if LOGINDISABLED is listed with the capabilities.

Server capabilities may change after #starttls, #login, and #authenticate. Cached capabilities must be invalidated after this method completes. The TaggedResponse to #login may include updated capabilities in its IMAP::ResponseCode.

Sends a LOGOUT command [IMAP4rev1 §6.1.3] to inform the command to inform the server that the client is done with the connection.

Related: #disconnect

Sends a LSUB command [IMAP4rev1 §6.3.9] and returns a subset of names from the set of names that the user has declared as being “active” or “subscribed.” refname and mailbox are interpreted as for #list.

The return value is an array of IMAP::MailboxList objects.

Related: #subscribe, #unsubscribe, #list, IMAP::MailboxList

Sends a MOVE command [RFC6851 §3.1] [IMAP4rev2 §6.4.8] to move the specified message(s) to the end of the specified destination mailbox. The set parameter is a number, an array of numbers, or a Range object. The number is a message sequence number.

Related: #uid_move

Capabilities

The server’s capabilities must include MOVE [RFC6851].

If UIDPLUS [RFC4315] is supported, the server’s response should include a COPYUID response code with IMAP::UIDPlusData. This will report the UIDVALIDITY of the destination mailbox, the UID set of the source messages, and the assigned UID set of the moved messages.

Sends a NAMESPACE command [RFC2342 §5] and returns the namespaces that are available. The NAMESPACE command allows a client to discover the prefixes of namespaces used by a server for personal mailboxes, other users’ mailboxes, and shared mailboxes.

The return value is a IMAP::Namespaces object which has personal, other, and shared fields, each an array of IMAP::Namespace objects. These arrays will be empty when the server responds with nil.

Many IMAP servers are configured with the default personal namespaces as ("" "/"): no prefix and the “/” hierarchy delimiter. In that common case, the naive client may not have any trouble naming mailboxes. But many servers are configured with the default personal namespace as e.g. ("INBOX." "."), placing all personal folders under INBOX, with “.” as the hierarchy delimiter. If the client does not check for this, but naively assumes it can use the same folder names for all servers, then folder creation (and listing, moving, etc) can lead to errors.

From RFC2342:

Although typically a server will support only a single Personal
Namespace, and a single Other User's Namespace, circumstances exist
where there MAY be multiples of these, and a client MUST be prepared
for them.  If a client is configured such that it is required to create
a certain mailbox, there can be circumstances where it is unclear which
Personal Namespaces it should create the mailbox in.  In these
situations a client SHOULD let the user select which namespaces to
create the mailbox in.

Related: #list, IMAP::Namespaces, IMAP::Namespace

For example:

capabilities = imap.capability
if capabilities.include?("NAMESPACE")
  namespaces = imap.namespace
  if namespace = namespaces.personal.first
    prefix = namespace.prefix  # e.g. "" or "INBOX."
    delim  = namespace.delim   # e.g. "/" or "."
    # personal folders should use the prefix and delimiter
    imap.create(prefix + "foo")
    imap.create(prefix + "bar")
    imap.create(prefix + %w[path to my folder].join(delim))
  end
end

Capabilities

The server’s capabilities must include NAMESPACE [RFC2342].

Sends a NOOP command [IMAP4rev1 §6.1.2] to the server.

This allows the server to send unsolicited untagged EXPUNGE #responses, but does not execute any client request. IMAP servers are permitted to send unsolicited untagged responses at any time, except for EXPUNGE.

• EXPUNGE can only be sent while a command is in progress.

• EXPUNGE must not be sent during #fetch, #store, or #search.

• EXPUNGE may be sent during #uid_fetch, #uid_store, or #uid_search.

Related: #idle, #check

Removes the response handler.

Sends a RENAME command [IMAP4rev1 §6.3.5] to change the name of the mailbox to newname.

A IMAP::NoResponseError is raised if a mailbox with the name mailbox cannot be renamed to newname for whatever reason; for instance, because mailbox does not exist, or because there is already a mailbox with the name newname.

Related: #create, #delete

Sends a SEARCH command [IMAP4rev1 §6.4.4] to search the mailbox for messages that match the given searching criteria, and returns message sequence numbers. keys can either be a string holding the entire search string, or a single-dimension array of search keywords and arguments.

Related: #uid_search

Search criteria

For a full list of search criteria, see [IMAP4rev1 §6.4.4], or [IMAP4rev2 §6.4.4], in addition to documentation for any [CAPABILITIES] reported by #capability which may define additional search filters, e.g: CONDSTORE, WITHIN, FILTERS, SEARCH=FUZZY, OBJECTID, or SAVEDATE. The following are some common search criteria:

<message set>

a set of message sequence numbers. “,” indicates an interval, “:” indicates a range. For instance, “2,10:12,15” means “2,10,11,12,15”.

BEFORE <date>

messages with an internal date strictly before <date>. The date argument has a format similar to 8-Aug-2002, and can be formatted using Net::IMAP.format_date.

BODY <string>

messages that contain <string> within their body.

CC <string>

messages containing <string> in their CC field.

FROM <string>

messages that contain <string> in their FROM field.

NEW

messages with the Recent, but not the Seen, flag set.

NOT <search-key>

negate the following search key.

OR <search-key> <search-key>

“or” two search keys together.

ON <date>

messages with an internal date exactly equal to <date>, which has a format similar to 8-Aug-2002.

SINCE <date>

messages with an internal date on or after <date>.

SUBJECT <string>

messages with <string> in their subject.

TO <string>

messages with <string> in their TO field.

For example:

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

Sends a SELECT command [IMAP4rev1 §6.3.1] to select a mailbox so that messages in the mailbox can be accessed.

After you have selected a mailbox, you may retrieve the number of items in that mailbox from imap.responses["EXISTS"][-1], and the number of recent messages from imap.responses["RECENT"][-1]. Note that these values can change if new messages arrive during a session or when existing messages are expunged; see #add_response_handler for a way to detect these events.

A IMAP::NoResponseError is raised if the mailbox does not exist or is for some reason non-selectable.

Related: #examine

Capabilities

If [UIDPLUS] is supported, the server may return an untagged “NO” response with a “UIDNOTSTICKY” response code indicating that the mailstore does not support persistent UIDs:

@responses["NO"].last.code.name == "UIDNOTSTICKY"

Sends a SETACL command [RFC4314 §3.1] along with mailbox, user and the rights that user is to have on that mailbox. If rights is nil, then that user will be stripped of any rights to that mailbox.

Related: #getacl

Capabilities

The server’s capabilities must include ACL [RFC4314].

Sends a SETQUOTA command [RFC2087 §4.1] along with the specified mailbox and quota. If quota is nil, then quota will be unset for that mailbox. Typically one needs to be logged in as a server admin for this to work.

Related: #getquota, #getquotaroot

Capabilities

The server’s capabilities must include QUOTA [RFC2087].

Sends a SORT command [RFC5256 §3] to search a mailbox for messages that match search_keys and return an array of message sequence numbers, sorted by sort_keys. search_keys are interpreted the same as for #search.

Related: #uid_sort, #search, #uid_search, #thread, #uid_thread

For example:

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]

Capabilities

The server’s capabilities must include SORT [RFC5256].