mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-09 20:12:13 +00:00
70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# kumo.disconnect
|
|
|
|
{{since('2025.10.06-5ec871ab')}}
|
|
|
|
```lua
|
|
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](reject.md) and leave the connection established.
|
|
|
|
### Disconnect with a 421
|
|
|
|
```lua
|
|
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.
|
|
|
|
```lua
|
|
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
|
|
|
|
```lua
|
|
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)
|
|
```
|
|
|