Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

422 lines (398 sloc) 10.707 kb

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

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_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
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_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
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
Jump to Line
Something went wrong with that request. Please try again.