SMTP Enhanced Errors: SMTP Service Extension for Returning Enhanced Error Codes
Lets an SMTP server put machine-readable status codes like 5.1.1 in front of its reply text.
Freed, N., "SMTP Service Extension for Returning Enhanced Error Codes", RFC 2034, DOI 10.17487/RFC2034, October 1996, <https://www.rfc-editor.org/info/rfc2034>.
@misc{rfc2034,
series = {Request for Comments},
number = 2034,
howpublished = {RFC 2034},
publisher = {RFC Editor},
doi = {10.17487/RFC2034},
url = {https://www.rfc-editor.org/info/rfc2034},
author = {N. Freed},
title = {{SMTP Service Extension for Returning Enhanced Error Codes}},
pagetotal = 6,
year = 1996,
month = oct,
} RFC text
Contents
Network Working Group N. Freed
Request for Comments: RFC 2034 Innosoft
Category: Standards Track October 1996
SMTP Service Extension for
Returning Enhanced Error Codes
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
1. Abstract
This memo defines an extension to the SMTP service [RFC-821, RFC-
1869] whereby an SMTP server augments its responses with the enhanced
mail system status codes defined in RFC 1893. These codes can then
be used to provide more informative explanations of error conditions,
especially in the context of the delivery status notifications format
defined in RFC 1894.
2. Introduction
Although SMTP is widely and robustly deployed, various extensions
have been requested by parts of the Internet community. In
particular, in the modern, international, and multilingual Internet a
need exists to assign codes to specific error conditions that can be
translated into different languages. RFC 1893 defines such a set of
status codes and RFC 1894 defines a mechanism to send such coded
material to users. However, in many cases the agent creating the RFC
1894 delivery status notification is doing so in response to errors
it received from a remote SMTP server.
As such, remote servers need a mechanism for embedding enhanced
status codes in their responses as well as a way to indicate to a
client when they are in fact doing this. This memo uses the SMTP
extension mechanism described in RFC 1869 to define such a mechanism.
3. Framework for the Enhanced Error Statuses Extension
The enhanced error statuses transport extension is laid out as
follows:
(1) the name of the SMTP service extension defined here is
Enhanced-Status-Codes;
(2) the EHLO keyword value associated with the extension is
ENHANCEDSTATUSCODES;
(3) no parameter is used with the ENHANCEDSTATUSCODES EHLO
keyword;
(4) the text part of all 2xx, 4xx, and 5xx SMTP responses
other than the initial greeting and any response to
HELO or EHLO are prefaced with a status code as defined
in RFC 1893. This status code is always followed by one
or more spaces.
(5) no additional SMTP verbs are defined by this extension;
and,
(6) the next section specifies how support for the
extension affects the behavior of a server and client
SMTP.
4. The Enhanced-Status-Codes service extension
Servers supporting the Enhanced-Status-Codes extension must preface
the text part of almost all response lines with a status code. As in
RFC 1893, the syntax of these status codes is given by the ABNF:
status-code ::= class "." subject "." detail
class ::= "2" / "4" / "5"
subject ::= 1*3digit
detail ::= 1*3digit
These codes must appear in all 2xx, 4xx, and 5xx response lines other
than initial greeting and any response to HELO or EHLO. Note that 3xx
responses are NOT included in this list.
All status codes returned by the server must agree with the primary
response code, that is, a 2xx response must incorporate a 2.X.X code,
a 4xx response must incorporate a 4.X.X code, and a 5xx response must
incorporate a 5.X.X code.
When responses are continued across multiple lines the same status
code must appear at the beginning of the text in each line of the
response.
Servers supporting this extension must attach enhanced status codes
to their responses regardless of whether or not EHLO is employed by
the client.
5. Status Codes and Negotiation
This specification does not provide a means for clients to request
that status codes be returned or that they not be returned; a
compliant server includes these codes in the responses it sends
regardless of whether or not the client expects them. This is
somewhat different from most other SMTP extensions, where generally
speaking a client must specifically make a request before the
extended server behaves any differently than an unextended server.
The omission of client negotiation in this case is entirely
intentional: Given the generally poor state of SMTP server error code
implementation it is felt that any step taken towards more
comprehensible error codes is something that all clients, extended or
not, should benefit from.
IMPORTANT NOTE: The use of this approach in this extension should be
seen as a very special case. It MUST NOT be taken as a license for
future SMTP extensions to dramatically change the nature of SMTP
client-server interaction without proper announcement from the server
and a corresponding enabling command from the client.
6. Usage Example
The following dialogue illustrates the use of enhanced status codes
by a server:
S: <wait for connection on TCP port 25>
C: <open connection to server>
S: 220 dbc.mtview.ca.us SMTP service ready
C: EHLO ymir.claremont.edu
S: 250-dbc.mtview.ca.us says hello
S: 250 ENHANCEDSTATUSCODES
C: MAIL FROM:<ned@ymir.claremont.edu>
S: 250 2.1.0 Originator <ned@ymir.claremont.edu> ok
C: RCPT TO:<mrose@dbc.mtview.ca.us>
S: 250 2.1.5 Recipient <mrose@dbc.mtview.ca.us> ok
C: RCPT TO:<nosuchuser@dbc.mtview.ca.us>
S: 550 5.1.1 Mailbox "nosuchuser" does not exist
C: RCPT TO:<remoteuser@isi.edu>
S: 551-5.7.1 Forwarding to remote hosts disabled
S: 551 5.7.1 Select another host to act as your forwarder
C: DATA
S: 354 Send message, ending in CRLF.CRLF.
...
C: .
S: 250 2.6.0 Message accepted
C: QUIT
S: 221 2.0.0 Goodbye
The client that receives these responses might then send a
nondelivery notification of the general form:
Date: Mon, 11 Mar 1996 09:21:47 -0400
From: Mail Delivery Subsystem <mailer-daemon@ymir.claremont.edu>
Subject: Returned mail
To: <ned@ymir.claremont.edu>
MIME-Version: 1.0
Content-Type: multipart/report; report-type=delivery-status;
boundary="JAA13167.773673707/YMIR.CLAREMONT.EDU"
--JAA13167.773673707/YMIR.CLAREMONT.EDU
content-type: text/plain; charset=us-ascii
----- Mail was successfully relayed to
the following addresses -----
<mrose@dbc.mtview.ca.us>
----- The following addresses had delivery problems -----
<nosuchuser@dbc.mtview.ca.us>
(Mailbox "nosuchuser" does not exist)
<remoteuser@isi.edu>
(Forwarding to remote hosts disabled)
--JAA13167.773673707/YMIR.CLAREMONT.EDU
content-type: message/delivery-status
Reporting-MTA: dns; ymir.claremont.edu
Original-Recipient: rfc822;mrose@dbc.mtview.ca.us
Final-Recipient: rfc822;mrose@dbc.mtview.ca.us
Action: relayed
Status: 2.1.5 (Destination address valid)
Diagnostic-Code: smtp;
250 Recipient <mrose@dbc.mtview.ca.us> ok
Remote-MTA: dns; dbc.mtview.ca.us
Original-Recipient: rfc822;nosuchuser@dbc.mtview.ca.us
Final-Recipient: rfc822;nosuchuser@dbc.mtview.ca.us
Action: failed
Status: 5.1.1 (Bad destination mailbox address)
Diagnostic-Code: smtp;
550 Mailbox "nosuchuser" does not exist
Remote-MTA: dns; dbc.mtview.ca.us
Original-Recipient: rfc822;remoteuser@isi.edu
Final-Recipient: rfc822;remoteuser@isi.edu
Action: failed
Status: 5.7.1 (Delivery not authorized, message refused)
Diagnostic-Code: smtp;
551 Forwarding to remote hosts disabled
Select another host to act as your forwarder
Remote-MTA: dns; dbc.mtview.ca.us
--JAA13167.773673707/YMIR.CLAREMONT.EDU
content-type: message/rfc822
[original message goes here]
--JAA13167.773673707/YMIR.CLAREMONT.EDU--
Note that in order to reduce clutter the reporting MTA has omitted
enhanced status code information from the diagnostic-code fields it
has generated.
7. Security Considerations
Additional detail in server responses axiomatically provides
additional information about the server. It is conceivable that
additional information of this sort may be of assistance in
circumventing server security. The advantages of provides additional
information must always be weighed against the security implications
of doing so.
8. References
[RFC-821]
Postel, J., "Simple Mail Transfer Protocol", RFC 821,
August, 1982. (August, 1982).
[RFC-1869]
Rose, M., Stefferud, E., Crocker, C., Klensin, J., Freed,
N., "SMTP Service Extensions", RFC 1869, November, 1995.
[RFC-1893]
Vaudreuil, G., "Enhanced Mail System Status Codes", RFC
1893, January, 1996.
[RFC-1894]
Moore, K., Vaudreuil, G., "An Extensible Message Format
for Delivery Status Notifications", RFC 1894, January,
1996.
9. Author Address
Ned Freed
Innosoft International, Inc.
1050 East Garvey Avenue South
West Covina, CA 91790
USA
tel: +1 818 919 3600 fax: +1 818 919 3614
email: ned@innosoft.com
AI ELI5
On this page
§1Why SMTP Needed Enhanced Codes
This memo defines an extension to SMTP in which a server adds the enhanced mail system status codes of RFC 1893 to its replies. The text of an SMTP reply is meant for people and differs between servers. The RFC points to the needs of a modern, international, multilingual Internet, where error conditions should have codes that can be translated into different languages.
RFC 1894 defines delivery status notifications that carry such coded material to users. But the program that builds one is often reacting to an error it received from a remote SMTP server. So remote servers need a way to embed the codes in their replies and a way to tell a client that they are doing so. The extension uses the mechanism of RFC 1869 to do that.
Words in an error message change from place to place. A short code does not, so everyone can understand why the mail failed.
§3The Extension Framework
The RFC lays the extension out as a short list. The service extension is named Enhanced-Status-Codes, and the EHLO keyword is ENHANCEDSTATUSCODES. The keyword takes no parameter, and the extension defines no new SMTP verbs.
What it does change is the reply text. In all 2xx, 4xx and 5xx replies, other than the initial greeting and any response to HELO or EHLO, the text is prefaced with a status code as defined in RFC 1893. The code is always followed by one or more spaces.
A server says a special word to announce that it adds codes. After that, every success or failure message starts with its code.
§4Where the Codes Go and What They Look Like
A status code has three numbers separated by dots: a class, a subject and a detail. The ABNF is status-code ::= class "." subject "." detail, where the class is 2, 4 or 5 and the subject and detail are each one to three digits.
The codes must agree with the primary reply code. A 2xx reply carries a 2.X.X code, a 4xx reply a 4.X.X code and a 5xx reply a 5.X.X code. Intermediate 3xx replies are not included. When a reply spans several lines, the same status code must appear at the start of the text on every line.
Servers supporting the extension must attach the codes whether or not the client used EHLO.
The code is like a label with a number, a topic and a detail, and its first number must match whether things went well, need a retry, or failed for good.
§5No Client Opt-In
Most SMTP extensions only change server behavior after the client asks. This one does not. The specification gives clients no way to ask for the codes or to refuse them, and a compliant server includes them regardless of what the client expects.
The RFC says this omission is entirely intentional. Because of the generally poor state of SMTP server error code implementation, any step toward more comprehensible error codes should benefit all clients, extended or not.
The RFC stresses that this is a very special case. It MUST NOT be taken as a license for future SMTP extensions to dramatically change SMTP client-server interaction without server announcement and a corresponding enabling command from the client.
Usually you have to ask for extras. Here the server gives the codes to everyone, because clearer errors are good for everybody.
§6A Worked Dialogue
The RFC shows a session. After EHLO the server advertises ENHANCEDSTATUSCODES. The MAIL command gets 250 2.1.0 and the first recipient 250 2.1.5. A second recipient gets 550 5.1.1 Mailbox "nosuchuser" does not exist. A third gets a two-line 551 reply with 5.7.1 on both lines. The accepted message gets 250 2.6.0 and QUIT gets 221 2.0.0.
The RFC then shows a nondelivery notification a client might build from this. The per-recipient Status: fields hold the codes, such as 5.1.1 for a bad destination mailbox address. The example notes that the reporting MTA omitted the enhanced codes from its diagnostic-code fields to reduce clutter.
The example shows a mail run where one address is fine and two are not. Each answer carries a code, and the bounce message turns them into plain reasons.
- EHLO ymir.claremont.edu
- 250 ENHANCEDSTATUSCODESThe server announces the extension.
- RCPT TO mrose@dbc.mtview.ca.us
- 250 2.1.5 Recipient ok
- RCPT TO nosuchuser@dbc.mtview.ca.us
- 550 5.1.1 Mailbox does not existThe reply code 550 and status code 5.1.1 agree on class 5.
§7Security Considerations
The only concern raised is that extra detail in server replies gives away extra information about the server. The RFC notes that such information could conceivably help someone get around server security. The benefit of providing more detail must always be weighed against the security implications of doing so.
The more a server says about why it said no, the more a sneaky person learns, so servers should think about how much to tell.