Custom Return Codes

All plugins return constants back to Haraka to denote how the client should be responded to for a particular hook.

These constants include DENY, DENYSOFT and DENYDISCONNECT which will 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 module was designed to allow a plugin to return RFC 3463 compliant extended status codes and to allow a plugin author to override the SMTP status code returned by Haraka.

The DSN module exposes a callable function for each status condition defined in RFC 3463.

Please refer to RFC 3463 for further information and background.

###Using the DSN module in your plugin

Firstly you need to load the DSN module by adding the following line to the top of your plugin:

var DSN = require('./dsn');

Then instead of:

return next(DENY, 'No such user');

You can call the DSN module and return that in place of optional message argument of next():

return 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 will be used.

[code] is optional and should be a numeric SMTP status code that should be returned to the client.

###Available DSN functions

<table width=”100%” border=1>

Function Default SMTP Status Code Enhanced Status Code Default Message <th colspan=5>Class: Other or Undefined Status X.0.0</th> unspecified 450 X.0.0 Other undefined status <th colspan=5>Class: Addressing Status X.1.X</th> addr_unspecified 450 X.1.0 Other address status addr_bad_dest_mailbox 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 220 X.1.5 Destination address valid addr_mbox_mobed 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 <th colspan=4>Class: Mailbox Status X.2.X</th> 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 <th colspan=4>Class: Mail System Status X.3.X</th> 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 <th colspan=4>Class: Network and Routing Status X.4.X</th> 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 <th colspan=4>Class: Mail Delivery Protocol Status X.5.X</th> 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_recipients 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 <th colspan=4>Class: Message Content or Media Status X.6.X</th> 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 <th colspan=4>Class: Security or Policy Status X.7.X</th> 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 <th colspan=4>Convenience functions</th> 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