.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Qpsmtpd::DSN 3pm"
.TH Qpsmtpd::DSN 3pm "2023-08-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Qpsmtpd::DSN \- Enhanced Mail System Status Codes \- RFC 1893
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBQpsmtpd::DSN\fR implements the \fIEnhanced Mail System Status Codes\fR from
\&\s-1RFC 1893.\s0
.SH "USAGE"
.IX Header "USAGE"
Any \fBqpsmtpd\fR plugin can access these status codes. All sub routines are used
the same way:
 use Qpsmtpd::DSN;
 ...;
 return Qpsmtpd::DSN\->\fBrelaying_denied()\fR;
.PP
or
.PP
.Vb 1
\& return Qpsmtpd::DSN\->relaying_denied("Relaying from $ip denied");
.Ve
.PP
or
.PP
.Vb 1
\& return Qpsmtpd::DSN\->relaying_denied(DENY,"Relaying from $ip denied");
.Ve
.PP
If no status message was given, it will use the predefined one from the 
\&\s-1RFC.\s0 If the first argument is numeric, it will use this as a return code, 
else the default return code is used. See below which default return code
is used in the different functions.
.PP
The first example will return 
\&\fI(\s-1DENY,\s0 \*(L"Relaying denied\*(R");\fR
the others 
\&\fI(\s-1DENY,\s0 \*(L"Relaying from \f(CI$ip\fI denied\*(R");\fR
which will be returned to qpsmtpd.
.PP
In those sub routines which don't start with \fIaddr_, sys_, net_, proto_, 
media_, sec_\fR I've added a default message which describes the status better
than the \s-1RFC\s0 message.
.SH "ADDRESS STATUS"
.IX Header "ADDRESS STATUS"
.IP "addr_unspecified" 9
.IX Item "addr_unspecified"
X.1.0
default: \s-1DENYSOFT\s0
.IP "no_such_user, addr_bad_dest_mbox" 9
.IX Item "no_such_user, addr_bad_dest_mbox"
X.1.1
default: \s-1DENY\s0
.IP "addr_bad_dest_system" 9
.IX Item "addr_bad_dest_system"
X.1.2
default: \s-1DENY\s0
.IP "addr_bad_dest_syntax" 9
.IX Item "addr_bad_dest_syntax"
X.1.3
default: \s-1DENY\s0
.IP "addr_dest_ambigous" 9
.IX Item "addr_dest_ambigous"
X.1.4
default: \s-1DENYSOFT\s0
.IP "addr_rcpt_ok" 9
.IX Item "addr_rcpt_ok"
X.1.5
default: \s-1OK\s0
.IP "addr_mbox_moved" 9
.IX Item "addr_mbox_moved"
X.1.6
default: \s-1DENY\s0
.IP "addr_bad_from_syntax" 9
.IX Item "addr_bad_from_syntax"
X.1.7
default: \s-1DENY\s0
.IP "addr_bad_from_system" 9
.IX Item "addr_bad_from_system"
X.1.8
default: \s-1DENY\s0
.SH "MAILBOX STATUS"
.IX Header "MAILBOX STATUS"
.IP "mbox_unspecified" 5
.IX Item "mbox_unspecified"
X.2.0
default: \s-1DENYSOFT\s0
.IP "mbox_disabled" 5
.IX Item "mbox_disabled"
X.2.1
default: \s-1DENY ..\s0.but \s-1RFC\s0 says:
   The mailbox exists, but is not accepting messages.  This may
   be a permanent error if the mailbox will never be re-enabled
   or a transient error if the mailbox is only temporarily
   disabled.
.IP "mbox_full" 5
.IX Item "mbox_full"
X.2.2
default: \s-1DENYSOFT\s0
.IP "mbox_msg_too_long" 5
.IX Item "mbox_msg_too_long"
X.2.3
default: \s-1DENY\s0
.IP "mbox_list_expansion_problem" 5
.IX Item "mbox_list_expansion_problem"
X.2.4
default: \s-1DENYSOFT\s0
.SH "MAIL SYSTEM STATUS"
.IX Header "MAIL SYSTEM STATUS"
.IP "sys_unspecified" 4
.IX Item "sys_unspecified"
X.3.0
default: \s-1DENYSOFT\s0
.IP "sys_disk_full" 4
.IX Item "sys_disk_full"
X.3.1
default: \s-1DENYSOFT\s0
.IP "sys_not_accepting_mail" 4
.IX Item "sys_not_accepting_mail"
X.3.2
default: \s-1DENYSOFT\s0
.IP "sys_not_supported" 4
.IX Item "sys_not_supported"
X.3.3
default: \s-1DENYSOFT\s0
          Selected features specified for the message are not
          supported by the destination system.  This can occur in
          gateways when features from one domain cannot be mapped onto
          the supported feature in another.
.IP "sys_msg_too_big" 4
.IX Item "sys_msg_too_big"
X.3.4
default \s-1DENY\s0
.SH "NETWORK AND ROUTING STATUS"
.IX Header "NETWORK AND ROUTING STATUS"
.IP "net_unspecified" 4
.IX Item "net_unspecified"
X.4.0
default: \s-1DENYSOFT\s0
.IP "net_directory_server_failed, temp_resolver_failed" 4
.IX Item "net_directory_server_failed, temp_resolver_failed"
X.4.3
default: \s-1DENYSOFT\s0
.IP "net_system_congested" 4
.IX Item "net_system_congested"
X.4.5
default: \s-1DENYSOFT\s0
.IP "net_routing_loop, too_many_hops" 4
.IX Item "net_routing_loop, too_many_hops"
X.4.6
default: \s-1DENY,\s0 but \s-1RFC\s0 says:
  A routing loop caused the message to be forwarded too many
  times, either because of incorrect routing tables or a user
  forwarding loop. This is useful only as a persistent
  transient error.
.Sp
Why do we want to \s-1DENYSOFT\s0 something like this?
.SH "MAIL DELIVERY PROTOCOL STATUS"
.IX Header "MAIL DELIVERY PROTOCOL STATUS"
.IP "proto_unspecified" 6
.IX Item "proto_unspecified"
X.5.0
default: \s-1DENYSOFT\s0
.IP "proto_invalid_command" 6
.IX Item "proto_invalid_command"
X.5.1
default: \s-1DENY\s0
.IP "proto_syntax_error" 6
.IX Item "proto_syntax_error"
X.5.2
default: \s-1DENY\s0
.IP "proto_rcpt_list_too_long, too_many_rcpts" 6
.IX Item "proto_rcpt_list_too_long, too_many_rcpts"
X.5.3
default: \s-1DENYSOFT\s0
.IP "proto_invalid_cmd_args" 6
.IX Item "proto_invalid_cmd_args"
X.5.4
default: \s-1DENY\s0
.IP "proto_wrong_version" 6
.IX Item "proto_wrong_version"
X.5.5
default: \s-1DENYSOFT\s0
.SH "MESSAGE CONTENT OR MESSAGE MEDIA STATUS"
.IX Header "MESSAGE CONTENT OR MESSAGE MEDIA STATUS"
.IP "media_unspecified" 5
.IX Item "media_unspecified"
X.6.0
default: \s-1DENYSOFT\s0
.IP "media_unsupported" 5
.IX Item "media_unsupported"
X.6.1
default: \s-1DENY\s0
.IP "media_conv_prohibited" 5
.IX Item "media_conv_prohibited"
X.6.2
default: \s-1DENY\s0
.IP "media_conv_unsupported" 5
.IX Item "media_conv_unsupported"
X.6.3
default: \s-1DENYSOFT\s0
.IP "media_conv_lossy" 5
.IX Item "media_conv_lossy"
X.6.4
default: \s-1DENYSOFT\s0
.SH "SECURITY OR POLICY STATUS"
.IX Header "SECURITY OR POLICY STATUS"
.IP "sec_unspecified" 8
.IX Item "sec_unspecified"
X.7.0
default: \s-1DENYSOFT\s0
.IP "sec_sender_unauthorized, bad_sender_ip, relaying_denied" 8
.IX Item "sec_sender_unauthorized, bad_sender_ip, relaying_denied"
X.7.1
default: \s-1DENY\s0
.IP "sec_list_dest_prohibited" 8
.IX Item "sec_list_dest_prohibited"
X.7.2
default: \s-1DENY\s0
.IP "sec_conv_failed" 8
.IX Item "sec_conv_failed"
X.7.3
default: \s-1DENY\s0
.IP "sec_feature_unsupported" 8
.IX Item "sec_feature_unsupported"
X.7.4
default: \s-1DENY\s0
.IP "sec_crypto_failure" 8
.IX Item "sec_crypto_failure"
X.7.5
default: \s-1DENY\s0
.IP "sec_crypto_algorithm_unsupported" 8
.IX Item "sec_crypto_algorithm_unsupported"
X.7.6
default: \s-1DENYSOFT\s0
.IP "sec_msg_integrity_failure" 8
.IX Item "sec_msg_integrity_failure"
X.7.7
default: \s-1DENY\s0