| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="utf-8"/> |
| <title>Apache James</title> |
| |
| <link rel="stylesheet" type="text/css" href="/assets/css/main.css"> |
| <link rel="stylesheet" type="text/css" href="/assets/css/font-awesome.min.css"> |
| <link rel="stylesheet" type="text/css" href="/assets/css/ie8.css"> |
| <link rel="stylesheet" type="text/css" href="/assets/css/ie9.css"> |
| <link rel="shortcut icon" href="/images/james-logo.png"> |
| </head> |
| <body> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <div id="wrapper"> |
| <div class="apache_ref"> |
| <a href="https://www.apache.org" alt="apache foundation link"><img src="https://www.apache.org/foundation/press/kit/asf_logo.svg" title="apache foundation logo"/></a> |
| </div> |
| <div class="apache_ref_mobile"> |
| <a href="https://www.apache.org" alt="apache foundation link">The Apache Software Foundation</a> |
| </div> |
| <div class="apache_ref_left"> |
| <a href="https://www.apache.org/events/current-event.html" alt="apache foundation event"><img src="https://www.apache.org/events/current-event-234x60.png" title="apache foundation event logo"/></a> |
| </div> |
| <div class="apache_ref_left_mobile"> |
| <a href="https://www.apache.org/events/current-event.html" alt="apache foundation event"><img src="https://www.apache.org/events/current-event-234x60.png" title="apache foundation event logo"/></a> |
| </div> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <header id="header" class="alt"> |
| <div class="logo"><a href="/index.html" alt="Apache James"><img src="/images/james.svg" alt="james logo"/></a></div> |
| <h1 class="hidden">James Enterprise Mail Server</h1> |
| <h2>Emails at the heart of your business logic</h2> |
| </header> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!-- Main --> |
| <div id="main"> |
| |
| <!-- Introduction --> |
| <section id="intro" class="main special"> |
| <div class=""> |
| <div class="content align-left"> |
| <header class="major"> |
| <h1><b>Configure Custom SMTP hooks</b></h1> |
| </header> |
| |
| <p> |
| The current project demonstrates how to write custom behaviors for Apache James SMTP server |
| by the means of SMTP hooks. |
| </p> |
| |
| <p> |
| SMTP hooks allow integrating third party systems with the SMTP stack and writing additional SMTP extensions, for |
| instance. |
| </p> |
| |
| <p> |
| Start by importing the dependencies: |
| </p> |
| |
| <pre><code><dependency> |
| <groupId>org.apache.james.protocols</groupId> |
| <artifactId>protocols-smtp/artifactId> |
| </dependency> |
| </code></pre> |
| |
| <ul>Allows writing the following hooks: |
| <li><b>AuthHook</b>: hook in the AUTH Command</li> |
| <li><b>HeloHook</b>: hook in the HELO Command</li> |
| <li><b>MailHook</b>: hook in the MAIL Command</li> |
| <li><b>MailParametersHook</b>: hook in the MAIL Command parameters</li> |
| <li><b>RcptHook</b>: hook in the RCPT Command</li> |
| <li><b>MessageHook</b>: hook in the DATA Command</li> |
| <li><b>QuitHook</b>: hook in the QUIT Command</li> |
| <li><b>UnknownHook</b>: hook for unknown commands</li> |
| </ul> |
| |
| <pre><code><dependency> |
| <groupId>org.apache.james</groupId> |
| <artifactId>james-server-protocols-smtp</artifactId> |
| </dependency> |
| </code></pre> |
| |
| <p>James comes bundled with <a href="http://james.apache.org/server/dev-provided-smtp-hooks.html">provided SMTP hooks for common features</a>. |
| We encourage you to review them before starting writing your own hooks.</p> |
| |
| <ul>Allows writing the following hooks: |
| <li><b>JamesMessageHook</b>: DATA command. Allows access to the message content.</li> |
| </ul> |
| |
| <header class="major"> |
| <h2><b>Writing your own hooks</b></h2> |
| </header> |
| |
| <p> |
| Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-smtp-hooks">GitHub</a>. |
| </p> |
| |
| <p> |
| In this example we implement a single RCPT hook: |
| </p> |
| |
| <pre><code>public class LoggingRcptHook implements RcptHook { |
| @Override |
| public HookResult doRcpt(SMTPSession session, MaybeSender sender, MailAddress rcpt, Map<String, String> parameters) { |
| System.out.println("RCPT TO " + rcpt + "with parameters " + parameters); |
| |
| // Continue the SMTP transaction |
| return HookResult.DECLINED; |
| } |
| } |
| </code></pre> |
| |
| <p>You can compile this example project:</p> |
| |
| <pre><code>mvn clean install</code></pre> |
| |
| <p>Then embed your extension into a James server. First configure your hook:</p> |
| |
| <pre><code><?xml version="1.0"?> |
| <smtpservers> |
| <smtpserver enabled="true"> |
| <jmxName>smtpserver-global</jmxName> |
| <bind>0.0.0.0:25</bind> |
| <connectionBacklog>200</connectionBacklog> |
| <tls socketTLS="false" startTLS="false"> |
| <keystore>file://conf/keystore</keystore> |
| <secret>james72laBalle</secret> |
| <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider> |
| <algorithm>SunX509</algorithm> |
| </tls> |
| <!-- ... --> |
| <handlerchain> |
| <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/> |
| <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/> |
| <handler class="org.apache.james.examples.LoggingRcptHook"/> |
| </handlerchain> |
| </smtpserver> |
| </smtpservers> |
| </code></pre> |
| |
| <p>Then start a James server with your JAR and the configuration:</p> |
| |
| <pre><code>docker run -d \ |
| -v $PWD/smtpserver.xml:/root/conf/smtpserver.xml \ |
| -v $PWD/exts:/root/extensions-jars \ |
| -p 25:25 \ |
| apache/james:memory-latest --generate-keystore |
| </code></pre> |
| |
| <p>You can play with <code>telnet</code> utility with the resulting server:</p> |
| |
| <pre><code>$ telnet 127.0.0.1 25 |
| Trying 127.0.0.1... |
| Connected to 127.0.0.1. |
| Escape character is '^]'. |
| 220 Apache JAMES awesome SMTP Server |
| EHLO toto.com |
| 250-177b73020637 Hello toto.com [172.17.0.1]) |
| 250-PIPELINING |
| 250-ENHANCEDSTATUSCODES |
| 250 8BITMIME |
| RCPT TO: <b@c.com> |
| 503 5.5.0 Need MAIL before RCPT |
| MAIL FROM: <b@c.com> |
| 250 2.1.0 Sender <b@c.com> OK |
| RCPT TO: <c@d.com> |
| 550 5.7.1 Requested action not taken: relaying denied |
| quit |
| </code></pre> |
| |
| <p> |
| Now looking at the logs we can verify that our RCPT have well been executed: |
| </p> |
| |
| <pre><code>06:49:15.734 [INFO ] o.a.j.GuiceJamesServer - JAMES server started |
| 06:49:30.275 [INFO ] o.a.j.p.n.BasicChannelUpstreamHandler - Connection established from 172.17.0.1 |
| 06:50:18.892 [INFO ] o.a.j.i.n.ImapChannelUpstreamHandler - Connection established from 172.17.0.1 |
| 06:50:19.152 [INFO ] o.a.j.i.n.ImapChannelUpstreamHandler - Connection closed for 172.17.0.1 |
| RCPT TO c@d.comwith parameters {TO:=, <c@d.com>=}</code></pre> |
| |
| <p>Note that hooks can also be written for the LMTP protocol.</p> |
| </div> |
| <footer class="major"> |
| <ul class="actions align-center"> |
| <li><a href="index.html" class="button">go back to other how-tos</a></li> |
| </ul> |
| </footer> |
| </div> |
| </section> |
| |
| </div> |
| |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <footer id="footer" class="major"> |
| <section> |
| <h2>James</h2> |
| <ul class="no-padding"> |
| <li class="no-padding"><a href="https://james.apache.org/#intro" class="active">About</a></li> |
| <li class="no-padding"><a href="https://james.apache.org/#first">Get Started</a></li> |
| <li class="no-padding"><a href="https://james.apache.org/#posts">Last Posts</a></li> |
| <li class="no-padding"><a href="https://james.apache.org/#second">Community</a></li> |
| <li class="no-padding"><a href="https://james.apache.org/#third">Contribute</a></li> |
| <li class="no-padding"><a href="https://james.apache.org/"><span class="fa fa-external-link"></span> Documentation</a></li> |
| </ul> |
| </section> |
| <section> |
| <h2>Connect</h2> |
| <ul class="icons"> |
| <li><a href="https://james.apache.org/mail.html" class="icon fa-envelope-o alt"><span class="label">Mailing-list</span></a></li> |
| <li><a href="https://gitter.im/apache/james-project" class="icon fa-wechat alt"><span class="label">Gitter</span></a></li> |
| <li><a href="https://github.com/apache/james-project" class="icon fa-github alt"><span class="label">GitHub</span></a></li> |
| <li><a href="https://twitter.com/ApacheJames" class="icon fa-twitter alt"><span class="label">Twitter</span></a></li> |
| <li><a href="https://james.apache.org/support.html" class="icon fa-briefcase alt"><span class="label">Support</span></a></li> |
| <li><a href="http://www.apache.org/events/current-event" class="icon fa-calendar alt"><span class="label">Apache Foundation events</span></a></li> |
| </ul> |
| </section> |
| <section class="legal-section"> |
| <h2>Copyright</h2> |
| Apache James and related projects are trademarks of the Apache Software Foundation.<br/> |
| <a href="https://www.apache.org/">Copyright 2006-2021 The Apache Software Foundation. All Rights Reserved.</a><br/> |
| <a href="https://www.apache.org/licenses/">License</a><br/> |
| <a href="https://www.apache.org/foundation/sponsorship.html">Donate</a> to support the Apache Foundation<br/> |
| <a href="https://www.apache.org/foundation/thanks.html">Thanks</a><br/> |
| Design: <a href="https://html5up.net">HTML5 UP</a><br/> |
| Thanks to <a href="http://www.neoma-interactive.com/">Neoma by Linagora</a> for the website design |
| </section> |
| </footer> |
| </div> |
| |
| </body> |
| </html> |