docs/modules/customization/pages/smtp-hooks.adoc

= Custom SMTP hooks
:navtitle: Custom SMTP hooks

SMTP hooks enable extending capabilities of the SMTP server and are run synchronously upon email reception, before the email is
enqueued in the MailQueue, and before any mail processing takes place.

== Available generic hooks

The following interfaces allows interacting with the following commands:

 * *AuthHook*: Implement this interfaces to hook in the AUTH Command.

....
    HookResult doAuth(SMTPSession session, Username username, String password);
....

 * *HeloHook*: Implement this interfaces to hook in the HELO Command

....
    HookResult doHelo(SMTPSession session, String helo);
....

 * *MailHook*: Implement this interfaces to hook in the MAIL Command

....
    HookResult doMail(SMTPSession session, MaybeSender sender);
....

 * *MailParametersHook*: Implement this interfaces to hook in the MAIL Command, this is called for specific mail arguments

....
    HookResult doMailParameter(SMTPSession session, String paramName, String paramValue);
....


 * *QuitHook*: Implement this interfaces to hook in the QUIT Command

....
    HookResult doQuit(SMTPSession session);
....

 * *RcptHook*: Implement this interfaces to hook in the RCPT Command

....
    HookResult doRcpt(SMTPSession session, MaybeSender sender, MailAddress rcpt);
....

 * *UnknownHook*: Hook for unknown commands

....
    HookResult doUnknown(SMTPSession session, String command);
....

== Custom hook registration

Register you hooks using xref:smtp.adoc[*smtpserver.xml*] handlerchain property.

== Writing additional SMTP commands

What to do if the Hook API is not enough for you ?

You want for example to write a code which handles a new command like "YOURCOOLCOMMAND: whatever@example".

For this kind of needs you should implement the CommandHandler interface. This gives you a lower-level API
to handle this kind of tasks. If you want to support a custom Hook in your CommandHandler its the best to
just extend AbstractHookableCmdHandler.