Skip to content

kumo.disconnect

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

kumo.disconnect(CODE, MESSAGE, REJECT_OR_DISCONNECT)

Calling kumo.disconnect will raise a lua error that will cause the current ESMTP event to respond with the SMTP error code and message that you specify, preferentially disconnecting the incoming SMTP session.

The parameters are:

  • CODE - Required integer. The SMTP code to use alongside your MESSAGE. Note that the SMTP protocol specification requires that a unilateral disconnection be sent with a 421 code. You can adjust/account for your conformance via the optional REJECT_OR_DISCONNECT parameter detailed below.
  • MESSAGE - Required string. The reason for the disconnection. If you intend to use ENHANCED STATUS CODES, you should prefix the message with your enhanced status code.
  • REJECT_OR_DISCONNECT - Optional string. Controls whether the connection will be disconnected or more simply rejected. It accepts the following possible values:
  • "ForceDisconnect" - disconnect the session immediately after sending your CODE and MESSAGE, even if CODE is not 421. Using this value with a non-421 code is technically non-conforming to the SMTP protocol specification.
  • "FollowWith421" - if the CODE is not 421, emit the CODE and MESSAGE, then synthesize a 421 HOSTNAME disconnecting due to previous error disconnection response to immediately follow it, and then disconnect.
  • "If421" - if the CODE is 421 disconnect the session. Otherwise, behave like kumo.reject and leave the connection established.

Disconnect with a 421

kumo.on('smtp_server_mail_from', function(sender)
  kumo.disconnect(421, 'mta.example.com go away!')
  -- this line is not reached
  -- The service responds to the peer with '421 mta.example.com go away!'
  -- and then drops the connection
end)

Disconnect with a non-standard exit code, non-SMTP-conformant

This example is not strictly conforming to SMTP, which requires that a 421 be used to indicate a disconnection. This may not matter in practice, but if it does matter for your use case, look at the example below this one.

kumo.on('smtp_server_mail_from', function(sender)
  kumo.disconnect(451, 'no thank you')
  -- this line is not reached
  -- The service responds to the peer with '451 no thank you'
  -- and then drops the connection
end)

Disconnect with a non-standard exit code, while remaining SMTP conformant

kumo.on('smtp_server_mail_from', function(sender)
  kumo.disconnect(451, 'no thank you', 'FollowWith421')
  -- this line is not reached
  -- The service responds to the peer with '451 no thank you\r\n421 HOSTNAME disconnecting due to previous error'
  -- and then drops the connection
end)