RFC 5530

RFC 5530: IMAP Response Codes 🎀

okay so bestie, this one is from May 2009 and it's written by A. Gulbrandsen from Oryx Mail Systems GmbH 💅 It's on the Standards Track, so it's an actual Internet standard, not just a vibe. The header doesn't list anything it obsoletes or updates, so it's standing on its own ✨

---

Status of This Memo 📜

ok so this document is a standards track protocol spec for the Internet community, and it's basically asking for feedback and suggestions 🫶 For where this protocol sits in the standardization process, check the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share it with everyone 🌈

Copyright Notice ©️

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, as in effect on the date of publication (http://trustee.ietf.org/license-info). Please read those carefully, because they spell out your rights and restrictions for this document 🧚

Abstract 🦋

IMAP responses are made of three things: a response type (OK, NO, BAD), an optional machine-readable response code, and some human-readable text 💖

This doc gathers a bunch of machine-readable response codes so servers and clients can talk to each other better and report errors more clearly 🔥

1. Introduction ✨

So, Section 7.1 of [RFC3501] already defines a bunch of response codes that help an IMAP client figure out why a command failed. But honestly? Experience has shown we need more codes 😭 For example, it's really useful for a client to know that an authentication attempt failed because the server had a problem, not because of a bad password 💅

Right now lots of IMAP servers use English, human-readable text to describe these errors, and a few clients try to translate that text into the user's language. Not ideal, bestie 🙈

This document names a bunch of errors as response codes. The codes are based on errors that some IMAP server implementations have already checked and reported, plus what some IMAP clients actually need 🌸

The best part? This document doesn't require any servers to test for these errors, and it doesn't require any clients to test for these names either. It just gives the errors names for better reporting and handling 🫶

2. Conventions Used in This Document 🎀

The formal syntax follows [RFC5234] as modified by [RFC3501] 🧚

Example lines that start with "C:" are sent by the client, and the ones that start with "S:" are sent by the server. "[...]" means some stuff got elided 💜

3. Response Codes 💖

This section defines all the new response codes. Each definition comes with one or more examples so you can see how it plays out 🔥

UNAVAILABLE 🌧️

Temporary failure because a subsystem is down. Like, an IMAP server that uses a Lightweight Directory Access Protocol (LDAP) or Radius server for authentication might send this when that LDAP/Radius server is offline 💀

C: a LOGIN "fred" "foo"
S: a NO [UNAVAILABLE] User's backend down for maintenance

AUTHENTICATIONFAILED 🔐

Authentication failed for some reason that the server isn't going to explain. Usually that means "unknown user" or "bad password" 🙈

This is basically the same as sending no response code at all, EXCEPT that when a client sees AUTHENTICATIONFAILED, it knows the problem wasn't something like UNAVAILABLE. So there's zero point in retrying the same login and password later 💅

C: b LOGIN "fred" "foo"
S: b NO [AUTHENTICATIONFAILED] Authentication failed

AUTHORIZATIONFAILED 🚫

Okay this one's giving main character energy 👑 Authentication worked for the authentication identity, but the server can't (or won't) let that identity act as the authorization identity it asked for. This only applies when the authentication and authorization identities are different 🌈

C: c1 AUTHENTICATE PLAIN
[...]
S: c1 NO [AUTHORIZATIONFAILED] No such authorization-ID

C: c2 AUTHENTICATE PLAIN
[...]
S: c2 NO [AUTHORIZATIONFAILED] Authenticator is not an admin

EXPIRED ⏰

So either authentication succeeded, or the server doesn't have the data it needs anymore. Either way, that passphrase can't get you in anymore 💔 The client or user should go get a new passphrase 🦋

C: d login "fred" "foo"
S: d NO [EXPIRED] That password isn't valid any more

PRIVACYREQUIRED 🔒

The operation isn't allowed because there isn't enough privacy 🫣 If Transport Layer Security (TLS) isn't in use, the client could try STARTTLS (see Section 6.2.1 of [RFC3501]) and then repeat the operation ✨

C: d login "fred" "foo"
S: d NO [PRIVACYREQUIRED] Connection offers no privacy

C: d select inbox
S: d NO [PRIVACYREQUIRED] Connection offers no privacy

CONTACTADMIN 📞

The user should reach out to the system administrator or the support desk 🧚

C: e login "fred" "foo"
S: e OK [CONTACTADMIN]

NOPERM 🚷

The access control system (like an Access Control List (ACL), see [RFC4314]) doesn't let this user carry out an operation, such as selecting or creating a mailbox 💅

C: f select "/archive/projects/experiment-iv"
S: f NO [NOPERM] Access denied

INUSE 🪑

The operation didn't happen because it would be sawing off a branch someone else is sitting on 💀 Someone else might be holding an exclusive lock that this operation needs, or the operation might involve deleting a resource someone else is using (usually a mailbox) 🙈

The operation may succeed if the client tries again later 🫶

C: g delete "/archive/projects/experiment-iv"
S: g NO [INUSE] Mailbox in use

EXPUNGEISSUED 🗑️

Someone else has issued an EXPUNGE for the same mailbox 👀 The client may want to issue NOOP soon. [RFC2180] goes deep on this topic if you want the full tea ☕

C: h search from fred@example.com
S: * SEARCH 1 2 3 5 8 13 21 42
S: h OK [EXPUNGEISSUED] Search completed

CORRUPTION 💥

The server found out that some relevant data (like the mailbox) is corrupt. This response code doesn't tell you what's corrupt, but the server can write that info to its logfiles 🪵

C: i select "/archive/projects/experiment-iv"
S: i NO [CORRUPTION] Cannot open mailbox

SERVERBUG 🐛

The server ran into a bug in itself, or it broke one of its own invariants. Oops 🙈

C: j select "/archive/projects/experiment-iv"
S: j NO [SERVERBUG] This should not happen

CLIENTBUG 🤭

The server detected a bug on the client side. This can come along with OK, NO, or BAD, depending on what the client bug actually is 🫣

C: k1 select "/archive/projects/experiment-iv"
[...]
S: k1 OK [READ-ONLY] Done
C: k2 status "/archive/projects/experiment-iv" (messages)
[...]
S: k2 OK [CLIENTBUG] Done

CANNOT 🚧

The operation breaks some invariant of the server, so it can never succeed. No amount of retrying is going to fix that, babe 💀

C: l create "///////"
S: l NO [CANNOT] Adjacent slashes are not supported

LIMIT 📏

The operation hit some implementation limit, like the number of flags on a single message or the number of flags used in a mailbox 🍓

C: m STORE 42 FLAGS f1 f2 f3 f4 f5 ... f250
S: m NO [LIMIT] At most 32 flags in one mailbox supported

OVERQUOTA 📦

The user would be over quota after the operation. (They might already be over quota, or they might not, and this code doesn't say which) 🤷‍♀️

Heads up though: if the server sends OVERQUOTA but doesn't support the IMAP QUOTA extension defined by [RFC2087], then there is a quota. The catch is that the client can't find out what the quota is 😭

C: n1 uid copy 1:* oldmail
S: n1 NO [OVERQUOTA] Sorry

C: n2 uid copy 1:* oldmail
S: n2 OK [OVERQUOTA] You are now over your soft quota

ALREADYEXISTS 👯

The operation tries to create something that's already there. For example, when the CREATE or RENAME directories try to create a mailbox and one with that name already exists 🙄

C: o RENAME this that
S: o NO [ALREADYEXISTS] Mailbox "that" already exists

NONEXISTENT 👻

The operation tries to delete something that doesn't exist. It's basically the opposite of ALREADYEXISTS 🫠

C: p RENAME this that
S: p NO [NONEXISTENT] No such mailbox

6. IANA Considerations ✨

okay so IANA made a whole IMAP Response Codes registry 🗂️ and it's already stacked with codes. here's the full list, verbatim:

NEWNAME              RFC 2060 (obsolete)
REFERRAL             RFC 2221
ALERT                RFC 3501
BADCHARSET           RFC 3501
PARSE                RFC 3501
PERMANENTFLAGS       RFC 3501
READ-ONLY            RFC 3501
READ-WRITE           RFC 3501
TRYCREATE            RFC 3501
UIDNEXT              RFC 3501
UIDVALIDITY          RFC 3501
UNSEEN               RFC 3501
UNKNOWN-CTE          RFC 3516
UIDNOTSTICKY         RFC 4315
APPENDUID            RFC 4315
COPYUID              RFC 4315
URLMECH              RFC 4467
TOOBIG               RFC 4469
BADURL               RFC 4469
HIGHESTMODSEQ        RFC 4551
NOMODSEQ             RFC 4551
MODIFIED             RFC 4551
COMPRESSIONACTIVE    RFC 4978
CLOSED               RFC 5162
NOTSAVED             RFC 5182
BADCOMPARATOR        RFC 5255
ANNOTATE             RFC 5257
ANNOTATIONS          RFC 5257
TEMPFAIL             RFC 5259
MAXCONVERTMESSAGES   RFC 5259
MAXCONVERTPARTS      RFC 5259
NOUPDATE             RFC 5267
METADATA             RFC 5464
NOTIFICATIONOVERFLOW RFC 5465
BADEVENT             RFC 5465
UNDEFINED-FILTER     RFC 5466
UNAVAILABLE          RFC 5530
AUTHENTICATIONFAILED RFC 5530
AUTHORIZATIONFAILED  RFC 5530
EXPIRED              RFC 5530
PRIVACYREQUIRED      RFC 5530
CONTACTADMIN         RFC 5530
NOPERM               RFC 5530
INUSE                RFC 5530
EXPUNGEISSUED        RFC 5530
CORRUPTION           RFC 5530
SERVERBUG            RFC 5530
CLIENTBUG            RFC 5530
CANNOT               RFC 5530
LIMIT                RFC 5530
OVERQUOTA            RFC 5530
ALREADYEXISTS        RFC 5530
NONEXISTENT          RFC 5530

the registry can be extended, bestie 🌸. you send a registration request to IANA, and IANA forwards it to a Designated Expert 🧑‍⚖️. that expert gets appointed by the responsible IESG Area Director, and the request gets CCed to the IMAP Extensions mailing list at ietf-imapext@imc.org (or whatever successor the Area Director picks). then the expert waits. either 30 days of community input on the IMAP Extensions list, or a successful IETF Last Call, whichever happens. after that, the expert decides if the registration is appropriate and either approves or disapproves it, sending the decision to the requestor with the IMAP Extensions list and IANA CCed.

if it gets denied, there has to be a justification, and where it's possible, the expert should also give concrete suggestions on how to change the request so it can be accepted. that's the kind of feedback loop i love to see 🫶.

each response code gets a list of relevant RFCs that describe (or extend) it. it can also get an optional response code status description, like "obsolete" or "reserved to prevent collision with deployed software". (note that in that second case the RFC number can be missing 👀.) if a status description is there, it means the response code is NOT RECOMMENDED for widespread use 🚫. no cap, that's the big flag.

the plan is that any future allocation comes with a published RFC, including direct submissions to the RFC Editor 📜. but to let codes get allocated before the RFC is approved for publication, the Designated Expert can approve allocations once it's clear an RFC will be published. for example, before IETF LC for the document.

the Designated Expert can also approve registrations for response codes that are already used in deployed software when no RFC exists. those registrations have to be marked "reserved to prevent collision with deployed software" 💅.

and response code registrations may not be deleted 🙅‍♀️. codes that are no longer believed appropriate (like if there's a problem with the syntax of the code, or if the spec describing it got moved to Historic) should be marked "obsolete" in the registry, clearly showing up in the lists IANA publishes. 💀 no deleting, just retiring with dignity.

---

7. Acknowledgements 🫶

big thank-you energy to Peter Coates, Mark Crispin, Philip Guenther, Alexey Melnikov, Ken Murchison, Chris Newman, Timo Sirainen, Philip Van Hoof, Dale Wiggins, and Sarah Wilkin 🌈✨. they helped with this document, and the whole thing is better because of them 💖.

---

8. References

8.1. Normative References

[RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
           4rev1", RFC 3501, March 2003.

[RFC5234]  Crocker, D., Ed., and P. Overell, "Augmented BNF for
           Syntax Specifications: ABNF", STD 68, RFC 5234, January
           2008.

9. Informative References 📚

[RFC2087]  Myers, J., "IMAP4 QUOTA extension", RFC 2087, January
           1997.

[RFC2180]  Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
           2180, July 1997.

[RFC4314]  Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
           RFC 4314, December 2005.

---

Author's Address 💌

Arnt Gulbrandsen
Oryx Mail Systems GmbH
Schweppermannstr. 8
D-81671 Muenchen
Germany

Fax: +49 89 4502 9758
EMail: arnt@oryx.com