haraka-dsn
Custom Return Codes
Plugins return constants to Haraka to specify how to respond to clients for a particular hook.
These constants include DENY, DENYSOFT and DENYDISCONNECT which automatically output an appropriate SMTP status code (e.g. 450 temporary failures for DENYSOFT or 550 permanent failures for DENY or DENYDISCONNECT) in the SMTP response sent back to the client along with an optional message text that you return as arguments to the next() function.
The DSN allows a plugin to return RFC compliant extended status codes and allows plugins to override the SMTP status code returned by Haraka.
The DSN module provides named helper functions for the most common status conditions. For less common codes, use DSN.create() directly. See the References section below for further information and background.
Using the DSN module in your plugin
Load the DSN module by adding the following line to the top of your plugin:
const DSN = require('haraka-dsn')Then instead of:
next(DENY, 'No such user')You can call the DSN module and return that in place of optional message argument of next():
next(DENY, DSN.no_such_user())This will cause Haraka to return the following back to the client:
`550 5.1.1 No such user`The DSN functions are used like this:
DSN.<function name>([message], [code]);The function name is required and maps to the list of defined status codes in RFC 3463. All of the available functions are detailed in the table below.
[message] is optional and should contain the message that you would like to be returned to the client, this value can be a string or an array which can contain multiple elements which will cause a multi-line reply to be sent to the client. If a message is not supplied, then the default message for the DSN function is used.
[code] is optional and should be a numeric SMTP status code to be returned to the client.
Available DSN functions
| Function | Default SMTP Status Code | Enhanced Status Code | Default Message | |
|---|---|---|---|---|
| Class: Other or Undefined Status X.0.0 | ||||
| unspecified | 450 | X.0.0 | Other undefined status | |
| Class: Addressing Status X.1.X | ||||
| addr_unspecified | 450 | X.1.0 | Other address status | |
| addr_bad_dest_mbox | 550 | X.1.1 | Bad destination mailbox address | |
| addr_bad_dest_system | 550 | X.1.2 | Bad destination system address | |
| addr_bad_dest_syntax | 550 | X.1.3 | Bad destination mailbox address syntax | |
| addr_dest_ambigous | 450 | X.1.4 | Destination mailbox address ambiguous | |
| addr_rcpt_ok | 250 | X.1.5 | Destination address valid | |
| addr_mbox_moved | 550 | X.1.6 | Destination mailbox has moved, No forwarding address | |
| addr_bad_from_syntax | 550 | X.1.7 | Bad sender"s mailbox address syntax | |
| addr_bad_from_system | 550 | X.1.8 | Bad sender"s system address | |
| Class: Mailbox Status X.2.X | ||||
| mbox_unspecified | 450 | X.2.0 | Other or undefined mailbox status | |
| mbox_disabled | 550 | X.2.1 | Mailbox disabled, not accepting messages | |
| mbox_full | 450 | X.2.2 | Mailbox full | |
| mbox_msg_too_long | 550 | X.2.3 | Message length exceeds administrative limit | |
| mbox_list_expansion_problem | 450 | X.2.4 | Mailing list expansion problem | |
| Class: Mail System Status X.3.X | ||||
| sys_unspecified | 450 | X.3.0 | Other or undefined mail system status | |
| sys_disk_full | 450 | X.3.1 | Mail system full | |
| sys_not_accepting_mail | 450 | X.3.2 | System not accepting network messages | |
| sys_not_supported | 450 | X.3.3 | System not capable of selected features | |
| sys_msg_too_big | 550 | X.3.4 | Message too big for system | |
| sys_incorrectly_configured | 450 | X.3.5 | System incorrectly configured | |
| Class: Network and Routing Status X.4.X | ||||
| net_unspecified | 450 | X.4.0 | Other or undefined network or routing status | |
| net_no_answer | 450 | X.4.1 | No answer from host | |
| net_bad_connection | 450 | X.4.2 | Bad connection | |
| net_directory_server_failed | 450 | X.4.3 | Directory server failure | |
| net_unable_to_route | 550 | X.4.4 | Unable to route | |
| net_system_congested | 450 | X.4.5 | Mail system congestion | |
| net_routing_loop | 550 | X.4.6 | Routing loop detected | |
| net_delivery_time_expired | 550 | X.4.7 | Delivery time expired | |
| Class: Mail Delivery Protocol Status X.5.X | ||||
| proto_unspecified | 450 | X.5.0 | Other or undefined protocol status | |
| proto_invalid_command | 550 | X.5.1 | Invalid command | |
| proto_syntax_error | 550 | X.5.2 | Syntax error | |
| proto_too_many_rcpts | 450 | X.5.3 | Too many recipients | |
| proto_invalid_cmd_args | 550 | X.5.4 | Invalid command arguments | |
| proto_wrong_version | 450 | X.5.5 | Wrong protocol version | |
| Class: Message Content or Media Status X.6.X | ||||
| media_unspecified | 450 | X.6.0 | Other or undefined media error | |
| media_unsupported | 550 | X.6.1 | Media not supported | |
| media_conv_prohibited | 550 | X.6.2 | Conversion required and prohibited | |
| media_conv_unsupported | 450 | X.6.3 | Conversion required but not supported | |
| media_conv_lossy | 450 | X.6.4 | Conversion with loss performed | |
| media_conv_failed | 450 | X.6.5 | Conversion failed | |
| Class: Security or Policy Status X.7.X | ||||
| sec_unspecified | 450 | X.7.0 | Other or undefined security status | |
| sec_unauthorized | 550 | X.7.1 | Delivery not authorized, message refused | |
| sec_list_expn_prohibited | 550 | X.7.2 | Mailing list expansion prohibited | |
| sec_conv_failed | 550 | X.7.3 | Security conversion required but not possible | |
| sec_feature_unsupported | 550 | X.7.4 | Security features not supported | |
| sec_crypto_failure | 550 | X.7.5 | Cryptographic failure | |
| sec_crypto_algo_unsupported | 450 | X.7.6 | Cryptographic algorithm not supported | |
| sec_msg_integrity_failure | 550 | X.7.7 | Message integrity failure | |
| Convenience functions | ||||
| no_such_user | 550 | X.1.1 | No such user | |
| temp_resolver_failed | 450 | X.4.3 | Temporary address resolution failure | |
| too_many_hops | 550 | X.4.6 | Too many hops | |
| bad_sender_ip | 550 | X.7.1 | Bad sender IP | |
| relaying_denied | 550 | X.7.1 | Relaying denied | |
| Authentication Status (RFC 4954) X.7.X | ||||
| auth_succeeded | 235 | X.7.0 | Authentication Succeeded | |
| auth_pass_transition_needed | 432 | X.7.12 | A password transition is needed | |
| auth_temp_fail | 454 | X.7.0 | Temporary authentication failure | |
| auth_too_weak | 534 | X.7.9 | Authentication mechanism is too weak | |
| auth_invalid | 535 | X.7.8 | Authentication credentials invalid | |
| auth_exch_too_long | 500 | X.5.6 | Authentication Exchange line is too long | |
| auth_required | 530 | X.7.0 | Authentication required | |
| auth_crypt_required | 538 | X.7.11 | Encryption required for requested authentication mechanism | |
| RFC 7505 — Null MX | ||||
| addr_null_mx | 556 | X.1.10 | Recipient address has null MX | |
| sec_null_mx_sender | 550 | X.7.27 | Sender address has null MX | |
| RFC 7372 — Email Authentication | ||||
| sec_dkim_no_pass | 550 | X.7.20 | No passing DKIM signature found | |
| sec_dkim_not_acceptable | 550 | X.7.21 | No acceptable DKIM signature found | |
| sec_dkim_no_author_match | 550 | X.7.22 | No valid author-matched DKIM signature found | |
| sec_spf_fail | 550 | X.7.23 | SPF validation failed | |
| sec_spf_error | 451 | X.7.24 | SPF validation error | |
| sec_rdns_fail | 550 | X.7.25 | Reverse DNS validation failed | |
| sec_multi_auth_fail | 550 | X.7.26 | Multiple authentication checks failed | |
References
- RFC 1893, obsoleted by RFC 3463 — SMTP Enhanced Status Codes
- RFC 3463 — Enhanced Mail System Status Codes
- RFC 3886 — Extended SMTP Delivery Status Notifications
- RFC 4468 — BURL IMAP
- RFC 4954 — SMTP Service Extension for Authentication
- RFC 5248 — A Registry for SMTP Enhanced Mail System Status Codes
- RFC 6710 — SMTP Extension for Message Transfer Priorities
- RFC 7293 — The Require-Recipient-Valid-Since Header Field
- RFC 7372 — Email Authentication Status Codes
- RFC 7504 — SMTP 521 and 556 Reply Codes
- RFC 7505 — A "Null MX" Resource Record for Domains That Accept No Mail