You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2019/05/07 04:24:31 UTC
[james-project] 03/03: JAMES-2716 howTo documentation for custom
listeners
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 6681d08baf5a3d5b67ca7445d40b5f1f580d5bfa
Author: Tran Tien Duc <dt...@linagora.com>
AuthorDate: Fri Apr 19 15:35:42 2019 +0700
JAMES-2716 howTo documentation for custom listeners
---
...stener.java => SetCustomFlagOnBigMessages.java} | 42 +-
.../src/main/resources/listeners.xml | 2 +-
...st.java => SetCustomFlagOnBigMessagesTest.java} | 54 +--
examples/pom.xml | 2 +-
src/homepage/_includes/footer.html | 35 ++
src/homepage/_includes/header.html | 6 +
src/homepage/_layouts/howTo.html | 42 ++
src/homepage/howTo/custom-listeners.html | 247 ++++++++++
src/homepage/howTo/deleted-messages-vault.html | 532 +++++++++------------
src/homepage/howTo/imap-server.html | 346 ++++++--------
src/homepage/howTo/index.html | 167 +++----
src/homepage/howTo/mail-processing.html | 370 ++++++--------
src/homepage/howTo/spf.html | 321 +++++--------
13 files changed, 1075 insertions(+), 1091 deletions(-)
diff --git a/examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/BigMessageListener.java b/examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessages.java
similarity index 67%
rename from examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/BigMessageListener.java
rename to examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessages.java
index 14f27f1..6b985d5 100644
--- a/examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/BigMessageListener.java
+++ b/examples/custom-listeners/src/main/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessages.java
@@ -24,21 +24,17 @@ import javax.mail.Flags;
import org.apache.james.mailbox.MailboxManager;
import org.apache.james.mailbox.MailboxSession;
-import org.apache.james.mailbox.MessageIdManager;
+import org.apache.james.mailbox.MessageManager;
import org.apache.james.mailbox.MessageManager.FlagsUpdateMode;
import org.apache.james.mailbox.MessageUid;
import org.apache.james.mailbox.events.Event;
import org.apache.james.mailbox.events.Group;
import org.apache.james.mailbox.events.MailboxListener;
import org.apache.james.mailbox.exception.MailboxException;
-import org.apache.james.mailbox.model.FetchGroupImpl;
-import org.apache.james.mailbox.model.MessageId;
-import org.apache.james.mailbox.model.MessageResult;
+import org.apache.james.mailbox.model.MessageRange;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-import com.google.common.collect.ImmutableList;
-
/**
* A Listener to determine the size of added messages.
*
@@ -46,25 +42,23 @@ import com.google.common.collect.ImmutableList;
* Then it will be considered as a big message and added BIG_MESSAGE {@value BIG_MESSAGE} flag
*
*/
-class BigMessageListener implements MailboxListener.GroupMailboxListener {
+class SetCustomFlagOnBigMessages implements MailboxListener.GroupMailboxListener {
- public static class BigMessageListenerGroup extends Group {
+ public static class PositionCustomFlagOnBigMessagesGroup extends Group {
}
- private static final BigMessageListenerGroup GROUP = new BigMessageListenerGroup();
- private static final Logger LOGGER = LoggerFactory.getLogger(BigMessageListener.class);
+ private static final PositionCustomFlagOnBigMessagesGroup GROUP = new PositionCustomFlagOnBigMessagesGroup();
+ private static final Logger LOGGER = LoggerFactory.getLogger(SetCustomFlagOnBigMessages.class);
static final long ONE_MB = 1000L * 1000L;
static String BIG_MESSAGE = "BIG_MESSAGE";
private final MailboxManager mailboxManager;
- private final MessageIdManager messageIdManager;
@Inject
- BigMessageListener(MailboxManager mailboxManager, MessageIdManager messageIdManager) {
+ SetCustomFlagOnBigMessages(MailboxManager mailboxManager) {
this.mailboxManager = mailboxManager;
- this.messageIdManager = messageIdManager;
}
@Override
@@ -84,24 +78,16 @@ class BigMessageListener implements MailboxListener.GroupMailboxListener {
private void setBigMessageFlag(Added addedEvent, MessageUid messageUid) {
try {
MailboxSession session = mailboxManager.createSystemSession(addedEvent.getUser().asString());
- MessageId messageId = addedEvent.getMetaData(messageUid).getMessageId();
-
- messageIdManager.getMessages(ImmutableList.of(messageId), FetchGroupImpl.MINIMAL, session)
- .forEach(messageResult -> setBigMessageFlag(messageResult, session));
- } catch (MailboxException e) {
- LOGGER.error("error happens when adding '{}' flag to big messages from user {}",
- BIG_MESSAGE, addedEvent.getUser().asString(), e);
- }
- }
+ MessageManager messageManager = mailboxManager.getMailbox(addedEvent.getMailboxId(), session);
- private void setBigMessageFlag(MessageResult messageResult, MailboxSession session) {
- try {
- messageIdManager.setFlags(
+ messageManager.setFlags(
new Flags(BIG_MESSAGE),
- FlagsUpdateMode.ADD, messageResult.getMessageId(), ImmutableList.of(messageResult.getMailboxId()), session);
+ FlagsUpdateMode.ADD,
+ MessageRange.one(messageUid),
+ session);
} catch (MailboxException e) {
- LOGGER.error("error happens when adding '{}' flag to message {}",
- BIG_MESSAGE, messageResult.getMessageId().serialize(), e);
+ LOGGER.error("error happens when adding '{}' flag to the message with uid {} in mailbox {} of user {}",
+ BIG_MESSAGE, messageUid.asLong(), addedEvent.getMailboxId(), addedEvent.getUser().asString(), e);
}
}
diff --git a/examples/custom-listeners/src/main/resources/listeners.xml b/examples/custom-listeners/src/main/resources/listeners.xml
index ebac3d6..c9b7177 100644
--- a/examples/custom-listeners/src/main/resources/listeners.xml
+++ b/examples/custom-listeners/src/main/resources/listeners.xml
@@ -20,6 +20,6 @@
<listeners>
<listener>
- <class>org.apache.james.examples.custom.listeners.BigMessageListener</class>
+ <class>org.apache.james.examples.custom.listeners.SetCustomFlagOnBigMessages</class>
</listener>
</listeners>
\ No newline at end of file
diff --git a/examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/BigMessageListenerTest.java b/examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessagesTest.java
similarity index 79%
rename from examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/BigMessageListenerTest.java
rename to examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessagesTest.java
index 5cdca0b..7075759 100644
--- a/examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/BigMessageListenerTest.java
+++ b/examples/custom-listeners/src/test/java/org/apache/james/examples/custom/listeners/SetCustomFlagOnBigMessagesTest.java
@@ -19,8 +19,8 @@
package org.apache.james.examples.custom.listeners;
-import static org.apache.james.examples.custom.listeners.BigMessageListener.BIG_MESSAGE;
-import static org.apache.james.examples.custom.listeners.BigMessageListener.ONE_MB;
+import static org.apache.james.examples.custom.listeners.SetCustomFlagOnBigMessages.BIG_MESSAGE;
+import static org.apache.james.examples.custom.listeners.SetCustomFlagOnBigMessages.ONE_MB;
import static org.assertj.core.api.Assertions.assertThat;
import java.nio.charset.StandardCharsets;
@@ -31,8 +31,8 @@ import javax.mail.Flags;
import org.apache.james.mailbox.DefaultMailboxes;
import org.apache.james.mailbox.MailboxSession;
import org.apache.james.mailbox.MailboxSessionUtil;
-import org.apache.james.mailbox.MessageIdManager;
import org.apache.james.mailbox.MessageManager;
+import org.apache.james.mailbox.MessageUid;
import org.apache.james.mailbox.events.Event;
import org.apache.james.mailbox.inmemory.InMemoryMailboxManager;
import org.apache.james.mailbox.inmemory.manager.InMemoryIntegrationResources;
@@ -40,8 +40,8 @@ import org.apache.james.mailbox.model.ComposedMessageId;
import org.apache.james.mailbox.model.FetchGroupImpl;
import org.apache.james.mailbox.model.MailboxId;
import org.apache.james.mailbox.model.MailboxPath;
-import org.apache.james.mailbox.model.MessageId;
import org.apache.james.mailbox.model.MessageMetaData;
+import org.apache.james.mailbox.model.MessageRange;
import org.apache.james.mailbox.model.MessageResult;
import org.apache.james.mailbox.store.event.EventFactory;
import org.apache.james.mime4j.dom.Message;
@@ -49,17 +49,16 @@ import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import com.google.common.base.Strings;
-import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Streams;
-class BigMessageListenerTest {
+class SetCustomFlagOnBigMessagesTest {
private static final String USER = "user";
private static final Event.EventId RANDOM_EVENT_ID = Event.EventId.random();
private static final MailboxPath INBOX_PATH = MailboxPath.forUser(USER, DefaultMailboxes.INBOX);
- private BigMessageListener testee;
+ private SetCustomFlagOnBigMessages testee;
private MessageManager inboxMessageManager;
- private MessageIdManager messageIdManager;
private MailboxId inboxId;
private MailboxSession mailboxSession;
private InMemoryMailboxManager mailboxManager;
@@ -68,29 +67,28 @@ class BigMessageListenerTest {
void beforeEach() throws Exception {
InMemoryIntegrationResources resources = InMemoryIntegrationResources.defaultResources();
mailboxManager = resources.getMailboxManager();
- messageIdManager = resources.getMessageIdManager();
mailboxSession = MailboxSessionUtil.create(USER);
inboxId = mailboxManager.createMailbox(INBOX_PATH, mailboxSession).get();
inboxMessageManager = mailboxManager.getMailbox(inboxId, mailboxSession);
- testee = new BigMessageListener(mailboxManager, messageIdManager);
+ testee = new SetCustomFlagOnBigMessages(mailboxManager);
resources.getEventBus().register(testee);
}
@Test
- void listeningEventShouldNotAddFlagWhenSmallMessages() throws Exception {
+ void shouldNotAddFlagWhenSmallMessages() throws Exception {
ComposedMessageId composedId = inboxMessageManager.appendMessage(
MessageManager.AppendCommand.builder()
.build(smallMessage()),
mailboxSession);
- assertThat(getMessageFlags(composedId.getMessageId()))
+ assertThat(getMessageFlags(composedId.getUid()))
.allSatisfy(flags -> assertThat(flags.contains(BIG_MESSAGE)).isFalse());
}
@Test
- void listeningEventShouldNotRemoveOtherFlagsWhenSmallMessages() throws Exception {
+ void shouldNotRemoveOtherFlagsWhenSmallMessages() throws Exception {
Flags appendMessageFlag = new Flags();
appendMessageFlag.add(Flags.Flag.SEEN);
appendMessageFlag.add(Flags.Flag.DRAFT);
@@ -101,7 +99,7 @@ class BigMessageListenerTest {
.build(smallMessage()),
mailboxSession);
- assertThat(getMessageFlags(composedId.getMessageId()))
+ assertThat(getMessageFlags(composedId.getUid()))
.allSatisfy(flags -> {
assertThat(flags.contains(Flags.Flag.SEEN)).isTrue();
assertThat(flags.contains(Flags.Flag.DRAFT)).isTrue();
@@ -109,26 +107,26 @@ class BigMessageListenerTest {
}
@Test
- void listeningEventShouldAddFlagWhenBigMessages() throws Exception {
+ void shouldAddFlagWhenBigMessages() throws Exception {
ComposedMessageId composedId = inboxMessageManager.appendMessage(
MessageManager.AppendCommand.builder()
.build(bigMessage()),
mailboxSession);
- assertThat(getMessageFlags(composedId.getMessageId()))
+ assertThat(getMessageFlags(composedId.getUid()))
.allSatisfy(flags -> assertThat(flags.contains(BIG_MESSAGE)).isTrue());
}
@Test
- void eventShouldAddFlagWhenMessageSizeIsEqualToBigMessageSize() throws Exception {
+ void shouldAddFlagWhenMessageSizeIsEqualToBigMessageSize() throws Exception {
ComposedMessageId composedIdOfSmallMessage = inboxMessageManager.appendMessage(
MessageManager.AppendCommand.builder()
.build(smallMessage()),
mailboxSession);
- MessageResult addedMessage = messageIdManager
- .getMessages(ImmutableList.of(composedIdOfSmallMessage.getMessageId()), FetchGroupImpl.MINIMAL, mailboxSession)
- .get(0);
+ MessageResult addedMessage = inboxMessageManager
+ .getMessages(MessageRange.one(composedIdOfSmallMessage.getUid()), FetchGroupImpl.MINIMAL, mailboxSession)
+ .next();
MessageMetaData oneMBMetaData = new MessageMetaData(addedMessage.getUid(), addedMessage.getModSeq(),
addedMessage.getFlags(), ONE_MB, addedMessage.getInternalDate(), addedMessage.getMessageId());
@@ -142,12 +140,12 @@ class BigMessageListenerTest {
testee.event(eventWithAFakeMessageSize);
- assertThat(getMessageFlags(composedIdOfSmallMessage.getMessageId()))
+ assertThat(getMessageFlags(composedIdOfSmallMessage.getUid()))
.allSatisfy(flags -> assertThat(flags.contains(BIG_MESSAGE)).isTrue());
}
@Test
- void listeningEventShouldNotRemoveOtherFlagsWhenBigMessages() throws Exception {
+ void shouldNotRemoveOtherFlagsWhenBigMessages() throws Exception {
Flags appendMessageFlag = new Flags();
appendMessageFlag.add(Flags.Flag.SEEN);
appendMessageFlag.add(Flags.Flag.DRAFT);
@@ -158,7 +156,7 @@ class BigMessageListenerTest {
.build(bigMessage()),
mailboxSession);
- assertThat(getMessageFlags(composedId.getMessageId()))
+ assertThat(getMessageFlags(composedId.getUid()))
.allSatisfy(flags -> {
assertThat(flags.contains(Flags.Flag.SEEN)).isTrue();
assertThat(flags.contains(Flags.Flag.DRAFT)).isTrue();
@@ -167,7 +165,7 @@ class BigMessageListenerTest {
}
@Test
- void listeningEventShouldKeepBigMessageFlagWhenAlreadySet() throws Exception {
+ void shouldKeepBigMessageFlagWhenAlreadySet() throws Exception {
Flags appendMessageFlag = new Flags();
appendMessageFlag.add(BIG_MESSAGE);
@@ -177,13 +175,13 @@ class BigMessageListenerTest {
.build(bigMessage()),
mailboxSession);
- assertThat(getMessageFlags(composedId.getMessageId()))
+ assertThat(getMessageFlags(composedId.getUid()))
.allSatisfy(flags -> assertThat(flags.contains(BIG_MESSAGE)).isTrue());
}
- private Stream<Flags> getMessageFlags(MessageId messageId) throws Exception {
- return messageIdManager.getMessages(ImmutableList.of(messageId), FetchGroupImpl.MINIMAL, mailboxSession)
- .stream()
+ private Stream<Flags> getMessageFlags(MessageUid messageUid) throws Exception {
+ return Streams.stream(inboxMessageManager
+ .getMessages(MessageRange.one(messageUid), FetchGroupImpl.MINIMAL, mailboxSession))
.map(MessageResult::getFlags);
}
diff --git a/examples/pom.xml b/examples/pom.xml
index 95b1b77..35bd283 100644
--- a/examples/pom.xml
+++ b/examples/pom.xml
@@ -32,8 +32,8 @@
<name>Apache James :: Examples</name>
<modules>
- <module>custom-mailets</module>
<module>custom-listeners</module>
+ <module>custom-mailets</module>
</modules>
</project>
\ No newline at end of file
diff --git a/src/homepage/_includes/footer.html b/src/homepage/_includes/footer.html
index 7acdb43..c88dc93 100644
--- a/src/homepage/_includes/footer.html
+++ b/src/homepage/_includes/footer.html
@@ -16,3 +16,38 @@
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-2018 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>
\ No newline at end of file
diff --git a/src/homepage/_includes/header.html b/src/homepage/_includes/header.html
index 7acdb43..7166497 100644
--- a/src/homepage/_includes/header.html
+++ b/src/homepage/_includes/header.html
@@ -16,3 +16,9 @@
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>
\ No newline at end of file
diff --git a/src/homepage/_layouts/howTo.html b/src/homepage/_layouts/howTo.html
new file mode 100644
index 0000000..d0e7180
--- /dev/null
+++ b/src/homepage/_layouts/howTo.html
@@ -0,0 +1,42 @@
+---
+layout: default
+---
+<!--
+ 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>
+
+ {% include header.html %}
+
+ {{ content }}
+
+ {% include footer.html %}
+</div>
diff --git a/src/homepage/howTo/custom-listeners.html b/src/homepage/howTo/custom-listeners.html
new file mode 100644
index 0000000..975c0d2
--- /dev/null
+++ b/src/homepage/howTo/custom-listeners.html
@@ -0,0 +1,247 @@
+---
+layout: howTo
+---
+<!--
+ 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 Listeners</b></h1>
+ </header>
+
+ <p>
+ This document will help you understand what is Mailbox Listener.
+ Then you will have a chance to implement your own Mailbox Listener and configure it to use it in James server.
+ </p>
+
+ <ul>
+ <li>What is Mailbox Listener</li>
+ <li>How to use a custom Mailbox Listener in James</li>
+ </ul>
+
+ <header class="major">
+ <h2><b>What is Mailbox Listener</b></h2>
+ </header>
+
+ <p>
+ Mailbox Listener is a component in James Mailbox System.
+ Each time an action is applied on a mailbox(adding, deleting), or on an email(adding, deleting, updating flags...),
+ then an event representing that action is generated and delivered to all the Listeners that had been registered before.
+ After receiving events, listeners retrieve information from the events then execute their business
+ (Indexing emails in ElasticSearch, updating quota of users, detecting spam emails...)
+ </p>
+
+ <p>
+ There are two kinds of Listener registration:
+ </p>
+ <ul>
+ <li>
+ <b>Group Registration</b>: a Group Registration will listen for all events fired and will deliver each event only once per group within a distributed topology.
+ That means if there are three listeners registered to the same group, each time an event is fired, only one of these three listeners can receive that event.
+ You can write your own custom Listener and configure James to register it as a Group Registration.
+ </li>
+ <li>
+ <b>Key Registration</b>: a Key Registration will listen only for events it is interested in, and with each event fired to a Key Registration, it will be
+ delivered to all registered listeners. That means if there are three listeners registered to the same key, each time an event is fired, all of three listeners will receive that event.
+ At the moment, James doesn't support to configure custom Listener for Key Registration.
+ This feature is used internally to implement things like IMAP IDLE aka notifications.
+ Therefore, it's not exposed through configurations as it makes little sense
+ </li>
+ </ul>
+
+ <header class="major">
+ <h2><b>How to use a custom Mailbox Listener in James</b></h2>
+ </header>
+
+ <p>
+ <b>prerequisite</b>: custom Mailbox Listeners can only work with James Guice products.
+ </p>
+
+ <header class="major">
+ <h3><b>Use the custom BigMessageListener in James</b></h3>
+ </header>
+
+ <p>
+ Once you have a custom Listener, it's very simple to setup James with that Listener.
+ In this example, we will use the
+ <a href="https://github.com/apache/james-project/blob/master/examples/custom-mailets/src/main/java/org/apache/james/examples/custom/listeners/BigMessageListener.java">BigMessageListener</a>
+ which will listen events fired after emails are appended to users mailboxes,
+ then for each email added event, determine the size of added email by getting size information from the event.
+ If the size of the email is greater than or equals 1 MB, then BigMessageListener will add a "BIG_MESSAGE" flag to that email
+ </p>
+
+ <header class="major">
+ <h3><b>Starting James with BigMessageListener</b></h3>
+ </header>
+
+ <p>We will take the simplest James product(JPA Guice) for the example</p>
+
+ <p>First, get template JPA product configuration:</p>
+ <pre><code>
+$ git clone https://github.com/apache/james-project
+$ cp -rf james-project/dockerfiles/run/guice/jpa/destination/conf conf
+ </code></pre>
+
+ <p>Then create the keystore file in the conf/ directory with the default password <code>james72laBalle</code>
+ <pre><code>
+$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
+ </code></pre>
+
+ <p>
+ Second, modify listener.xml configuration file in conf/ directory to use only BigMessageListener
+ by specifying its full class name. We only need to use this Listener in our example.
+ </p>
+ <pre><code>
+<listeners>
+ <listener>
+ <class>org.apache.james.examples.custom.listeners.SetCustomFlagOnBigMessages</class>
+ </listener>
+</listeners>
+ </code></pre>
+
+ <p>Finally, starting a James Server by docker compose</p>
+ <p>Getting James docker-compose.yml</p>
+ <pre><code>
+$ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml
+ </code></pre>
+ <p>Using James Guice JPA instead of the default product</p>
+ <pre><code>
+services:
+ james:
+ ...
+ image: linagora/james-jpa-guice:latest
+ </code></pre>
+ <p>Add the following volumes for james service:</p>
+ <pre><code>
+volumes:
+ - $PWD/conf:/root/conf/
+ </code></pre>
+
+ <p>
+ When you are using your listeners, place the jar containing your listeners into "extensions-jars" directory
+ and add a volume for it.
+ </p>
+ <pre><code>
+volumes:
+ - $PWD/extensions-jars:/root/extensions-jars/
+ </code></pre>
+ <p>
+ Putting compiled jars into extensions-jars directory
+ </p>
+ <p>
+ When you write a custom Listener, you have to compile it and place the compiled jar package inside "extensions-jars" directory
+ to make James load your Listener when it starts up.
+ In this case, you should compile the James's module <b>examples/custom-listeners</b> and put it to "extensions-jars".
+ The jar name can be sightly different by the time because its name carries James version, but you can recognize it easily.
+ </p>
+ <pre><code>
+$ mkdir extensions-jars
+$ cd james-project
+$ mvn clean install -DskipTests -f examples/custom-listeners/pom.xml
+$ cd ../
+$ cp james-project/examples/custom-listeners/target/custom-listeners-****.jar extensions-jars/custom-listeners.jar
+ </code></pre>
+ <p>
+ Check out the docker-compose.yml to get the host name of james service, currently it's <b>james.local</b>.
+ So you, have to modify James domain list to use this <b>james.local</b> as James default domain:
+ </p>
+ <pre><code>
+<domainlist>
+ <autodetect>true</autodetect>
+ <autodetectIP>true</autodetectIP>
+ <defaultDomain>james.local</defaultDomain>
+</domainlist>
+ </code></pre>
+ <p>
+ Now, you are able to start james by docker compose, then wait for all docker containers to be up.
+ </p>
+ <pre><code>
+$ docker-compose up -d
+ </code></pre>
+
+ <header class="major">
+ <h3><b>Verifying the result of the setup</b></h3>
+ </header>
+ <p>
+ Now that we have a proper James server on our local machine with custom listeners loaded, we are able to use them.
+ To verify our work, here is this simple scenario:
+ </p>
+ <ul>
+ <li>Use James CLI to create user1@james.local/password1</li>
+ <li>Use James CLI to create user2@james.local/password2</li>
+ <li>Use a mail client to connect to user1, send a big email to use2</li>
+ <li>Use IMAP command to see the flags of the email user2 had received</li>
+ </ul>
+
+ <p>Use James CLI to provision users</p>
+ <pre><code>
+$ docker exec -it james /bin/bash
+$ java -jar james-cli.jar AddUser user1@james.local password1
+$ java -jar james-cli.jar AddUser user2@james.local password2
+$ exit
+ </code></pre>
+
+ <p>
+ Use thunderbird or any mail client on your local machine to connect with user1 and user2.
+ The configuration should point to smpt server at <code>localhost:25</code>, and imap server at <code>localhost:143</code>.
+ Use these credentials: user1@james.local/password1 and user2@james.local/password2
+ </p>
+ <p>
+ After that, use user1@james.local account to sent a big email to user2@james.local, the size of the emails should be greater than 1 MB.
+ One of the simplest ways is to attach a picture bigger than 1MB to the mail.
+ </p>
+ <p>
+ If the mail client had sent a mail to user2@james.local, then you can see that this email appeared in user2 INBOX.
+ We can see its flags by using the following IMAP command on your local host.
+ </p>
+ <pre><code>
+$ telnet localhost 143
+
+# Login by user2
+A1 LOGIN user2@james.local password2
+
+# Select user2's INBOX
+A1 SELECT INBOX
+
+# Search for all emails in user2's INBOX. The result should be: * SEARCH 1. Where 1 is the UID of the email which had been sent before
+A1 UID SEARCH ALL
+
+# Display all flags of that email. The result should be: * 1 FETCH (FLAGS (\Recent \Seen BIG_MESSAGE)). You can see that BIG_MESSAGE has appeared
+A1 FETCH 1 (FLAGS)
+ </code></pre>
+ <p>
+ That's it, we are now sure that our BigMessageListener worked !
+ Now that you have learned how to set up a custom Listener, you can follow this setup to add your own !
+ </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>
diff --git a/src/homepage/howTo/deleted-messages-vault.html b/src/homepage/howTo/deleted-messages-vault.html
index 782278d..34d4459 100644
--- a/src/homepage/howTo/deleted-messages-vault.html
+++ b/src/homepage/howTo/deleted-messages-vault.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: howTo
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,303 +19,237 @@ layout: default
specific language governing permissions and limitations
under the License.
-->
-<link href="assets/css/lightbox.css" rel="stylesheet">
-<link href="assets/css/lity.min.css" rel="stylesheet" />
-<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>
-
- <!-- Header -->
- <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>
-
- <!-- Main -->
- <div id="main">
-
- <!-- Introduction -->
- <section id="intro" class="main special">
- <div class="">
- <div class="content align-left">
- <header class="major">
- <h1><b>Deleted Messages Vault</b></h1>
- </header>
-
- <p>
- This document will help you understand what is Deleted Messages Vault. And finally,
- present to you, how to setup James Server with this feature.
- </p>
-
- <ul>
- <li>What is Deleted Messages Vault</li>
- <li>How to setup James with Deleted Messages Vault</li>
- <li>How to administrate Deleted Messages Vault</li>
- </ul>
-
- <header class="major">
- <h2><b>What is Deleted Messages Vault</b></h2>
- </header>
-
- <p>Deleted Messages Vault is a feature in James, it allows you to:</p>
- <ul>
- <li>retain user deleted messages for some time</li>
- <li>restore & export deleted messages by various criteria</li>
- <li>permanently delete some retained messages</li>
- </ul>
-
- <p>
- If Deleted Messages Vault is enabled, when users delete their mails, James will retain these mails into Deleted Messages Vault.
- And only administrators can interact with this component via WebAdmin REST APIs.
- </p>
- <p>
- One useful use of that feature is to allow an administrator to restore some mails an user may have deleted by accident.
- However, mails are not retained forever as you have to configure a retention period before using it (we'll see later how to trigger the collection of mails).
- It's also possible to permanently delete a mail if needed.
- </p>
- <p>
- Deleted mails for exporting & restoring can be filtered via several criteria based on mail properties.
- At the moment, these are supported mail properties for filtering:
- </p>
- <ul>
- <li>deletion date(ISO-8601 Date String)
- <ul>
- <li>supports before or equals operator</li>
- <li>supports after or equals operator</li>
- </ul>
- </li>
- <li>delivery date(ISO-8601 Date String)
- <ul>
- <li>supports before or equals operator</li>
- <li>supports after or equals operator</li>
- </ul>
- </li>
- <li>recipients(List of string)
- <ul>
- <li>supports contains operator</li>
- </ul>
- </li>
- <li>sender(String)
- <ul>
- <li>supports equal matching operator</li>
- </ul>
- </li>
- <li>has attachment(Boolean)
- <ul>
- <li>supports equal matching operator</li>
- </ul>
- </li>
- <li>subject(String)
- <ul>
- <li>supports equal matching operator</li>
- <li>supports equal ignore case matching operator</li>
- <li>supports contains matching operator</li>
- <li>supports contains ignore case matching operator (with US locale)</li>
- </ul>
- </li>
- </ul>
-
- <header class="major">
- <h2><b>How to setup James with Deleted Messages Vault</b></h2>
- </header>
-
- <p>
- In this section, we will guide you to setup James with Deleted Message Vault by following below steps:
- </p>
- <ul>
- <li>Enable Deleted Messages Vault</li>
- <li>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</li>
- <li>Starting James with enabled Deleted Message Vault by docker compose</li>
- </ul>
-
- <header class="major">
- <h3><b>Enable Deleted Messages Vault</b></h3>
- </header>
-
- <p>
- To do this, you have to create a configuration file <b>deletedMessageVault.properties</b>, then put it into <b>conf</b> directory of James.
- There are two available properties you may want to configure:
- </p>
- <ul>
- <li>
- <b>urlPrefix</b>: represent for the prefix of namespace Deleted Messages Vault will use to store deleted messages.
- </li>
- <li>
- <b>retentionPeriod</b>: represent for the period deleted messages allowed to be stored in Deleted Messages Vault.
- </li>
- </ul>
-
- <p>
- Example:
- </p>
- <pre><code>
- urlPrefix=cassandra://var/deletedMessages/vault
- retentionPeriod=1 year
- </code></pre>
- <p>
- More details about configuration & example is at <a href="/server/config-vault.html">Deleted Messages Vault Configuration</a>
- </p>
-
- <header class="major">
- <h3><b>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</b></h3>
- </header>
-
- <p>
- By default, although Deleted Messages Vault has been configured, but, to make it really work, you still need to configure Pre Deletion Hooks to lets James use it.
- Before deleting a mail in James, PreDeletionHooks will be triggered to execute all hooks. If all hook executions success, then James will process to delete that mail.
- There is already a DeletedMessageVaultHook in James, its job to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file.
- </p>
-
- <p>
- Sample DeletedMessageVaultHook configuration:
- </p>
- <pre><code>
- <listeners>
- <listener>
- ...
- </listener>
- ...
- <preDeletionHook>
- <class>org.apache.james.vault.DeletedMessageVaultHook</class>
- </preDeletionHook>
- </listeners>
- </code></pre>
- <p>
- More details about configuration & example is at <a href="/server/config-listener.html">Pre Deletion Hook Configuration</a>
- </p>
-
- <header class="major">
- <h3><b>Starting James with enabled Deleted Message Vault by docker compose</b></h3>
- </header>
-
- <p>We will take James cassandra product for the example</p>
-
- <p>First, get template cassandra product configuration:</p>
- <pre><code>
- $ git clone https://github.com/apache/james-project
- $ cp -rf james-project/dockerfiles/run/guice/cassandra/destination/conf conf
- $ mv keystore conf/keystore
- </code></pre>
-
- <p>Second, modify deletedMessageVault.properties configuration file like an example at previous paragraph</p>
-
- <p>Third, modify listeners.xml to configure DeletedMessageVaultHook by adding preDeletionHook section at previous paragraph</p>
-
- <p>Fourth, We will create a local folder for holding data out of the container:</p>
- <pre><code>
- mkdir var
- </code></pre>
-
- <p>Finally, starting a James Server by docker compose</p>
- <p>Getting James docker-compose.yml</p>
- <pre><code>
- $ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml
- </code></pre>
-
- <p>Add the following volumes for james service:</p>
- <pre><code>
- volumes:
- - $PWD/conf:/root/conf/
- - $PWD/var:/root/var/
- </code></pre>
-
- <header class="major">
- <h2><b>How to administrate Deleted Messages Vault</b></h2>
- </header>
-
- <p>
- These are supported WebAdmin features on top of Deleted Messages Vault.
- You can have a look at WebAdmin Deleted Messages Vault document at <a href="https://james.apache.org/server/manage-webadmin.html#Deleted_Messages_Vault">here</a>
- </p>
-
- <header class="major">
- <h3><b>WebAdmin Deleted Messages Vault exporting</b></h3>
- </header>
-
- <p>
- This part is a bit special to you, you are able to choose which exporting mechanism to be used. At the moment there are one available exporting mechanism
- </p>
- <ul>
- <li><b>localFile</b>: This is a simple exporting mechanism while with an export request, it retrieves deleted mails from Deleted Messages Vault,
- then store them as a zip file in local file system in James Server. Then sending a mail with the absolute path of exported file to the targeted mail address.</li>
- </ul>
- <p>
- You can configure which kind of export mechanism to use in James by specifying <b>blob.export.implementation</b> in blobStore.properties configuration file.
- E.g:
- </p>
- <pre><code>
- blob.export.implementation=localFile
- </code></pre>
-
- <p>
- More details about configuration & example at <a href="/server/config-blob-expor.html">Blob Export Configuration</a>
- </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>
- <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-2018 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>
-<!-- Scripts -->
-<script src="assets/js/jquery.min.js"></script>
-<script src="assets/js/jquery.scrollex.min.js"></script>
-<script src="assets/js/jquery.scrolly.min.js"></script>
-<script src="assets/js/skel.min.js"></script>
-<script src="assets/js/util.js"></script>
-<script src="assets/js/lightbox.js"></script>
-<script src="assets/js/github-fetch.js"></script>
-<script src="assets/js/lity.min.js"></script>
-<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
-<script src="assets/js/main.js"></script>
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Deleted Messages Vault</b></h1>
+ </header>
+
+ <p>
+ This document will help you understand what is Deleted Messages Vault. And finally,
+ present to you, how to setup James Server with this feature.
+ </p>
+
+ <ul>
+ <li>What is Deleted Messages Vault</li>
+ <li>How to setup James with Deleted Messages Vault</li>
+ <li>How to administrate Deleted Messages Vault</li>
+ </ul>
+
+ <header class="major">
+ <h2><b>What is Deleted Messages Vault</b></h2>
+ </header>
+
+ <p>Deleted Messages Vault is a feature in James, it allows you to:</p>
+ <ul>
+ <li>retain user deleted messages for some time</li>
+ <li>restore & export deleted messages by various criteria</li>
+ <li>permanently delete some retained messages</li>
+ </ul>
+
+ <p>
+ If Deleted Messages Vault is enabled, when users delete their mails, James will retain these mails into Deleted Messages Vault.
+ And only administrators can interact with this component via WebAdmin REST APIs.
+ </p>
+ <p>
+ One useful use of that feature is to allow an administrator to restore some mails an user may have deleted by accident.
+ However, mails are not retained forever as you have to configure a retention period before using it (we'll see later how to trigger the collection of mails).
+ It's also possible to permanently delete a mail if needed.
+ </p>
+ <p>
+ Deleted mails for exporting & restoring can be filtered via several criteria based on mail properties.
+ At the moment, these are supported mail properties for filtering:
+ </p>
+ <ul>
+ <li>deletion date(ISO-8601 Date String)
+ <ul>
+ <li>supports before or equals operator</li>
+ <li>supports after or equals operator</li>
+ </ul>
+ </li>
+ <li>delivery date(ISO-8601 Date String)
+ <ul>
+ <li>supports before or equals operator</li>
+ <li>supports after or equals operator</li>
+ </ul>
+ </li>
+ <li>recipients(List of string)
+ <ul>
+ <li>supports contains operator</li>
+ </ul>
+ </li>
+ <li>sender(String)
+ <ul>
+ <li>supports equal matching operator</li>
+ </ul>
+ </li>
+ <li>has attachment(Boolean)
+ <ul>
+ <li>supports equal matching operator</li>
+ </ul>
+ </li>
+ <li>subject(String)
+ <ul>
+ <li>supports equal matching operator</li>
+ <li>supports equal ignore case matching operator</li>
+ <li>supports contains matching operator</li>
+ <li>supports contains ignore case matching operator (with US locale)</li>
+ </ul>
+ </li>
+ </ul>
+
+ <header class="major">
+ <h2><b>How to setup James with Deleted Messages Vault</b></h2>
+ </header>
+
+ <p>
+ In this section, we will guide you to setup James with Deleted Message Vault by following below steps:
+ </p>
+ <ul>
+ <li>Enable Deleted Messages Vault</li>
+ <li>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</li>
+ <li>Starting James with enabled Deleted Message Vault by docker compose</li>
+ </ul>
+
+ <header class="major">
+ <h3><b>Enable Deleted Messages Vault</b></h3>
+ </header>
+
+ <p>
+ To do this, you have to create a configuration file <b>deletedMessageVault.properties</b>, then put it into <b>conf</b> directory of James.
+ There are two available properties you may want to configure:
+ </p>
+ <ul>
+ <li>
+ <b>urlPrefix</b>: represent for the prefix of namespace Deleted Messages Vault will use to store deleted messages.
+ </li>
+ <li>
+ <b>retentionPeriod</b>: represent for the period deleted messages allowed to be stored in Deleted Messages Vault.
+ </li>
+ </ul>
+
+ <p>
+ Example:
+ </p>
+ <pre><code>
+urlPrefix=cassandra://var/deletedMessages/vault
+retentionPeriod=1 year
+ </code></pre>
+ <p>
+ More details about configuration & example is at <a href="/server/config-vault.html">Deleted Messages Vault Configuration</a>
+ </p>
+
+ <header class="major">
+ <h3><b>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</b></h3>
+ </header>
+
+ <p>
+ By default, although Deleted Messages Vault has been configured, but, to make it really work, you still need to configure Pre Deletion Hooks to lets James use it.
+ Before deleting a mail in James, PreDeletionHooks will be triggered to execute all hooks. If all hook executions success, then James will process to delete that mail.
+ There is already a DeletedMessageVaultHook in James, its job to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file.
+ </p>
+
+ <p>
+ Sample DeletedMessageVaultHook configuration:
+ </p>
+ <pre><code>
+<listeners>
+ <listener>
+ ...
+ </listener>
+ ...
+ <preDeletionHook>
+ <class>org.apache.james.vault.DeletedMessageVaultHook</class>
+ </preDeletionHook>
+</listeners>
+ </code></pre>
+ <p>
+ More details about configuration & example is at <a href="/server/config-listener.html">Pre Deletion Hook Configuration</a>
+ </p>
+
+ <header class="major">
+ <h3><b>Starting James with enabled Deleted Message Vault by docker compose</b></h3>
+ </header>
+
+ <p>We will take James cassandra product for the example</p>
+
+ <p>First, get template cassandra product configuration:</p>
+ <pre><code>
+$ git clone https://github.com/apache/james-project
+$ cp -rf james-project/dockerfiles/run/guice/cassandra/destination/conf conf
+ </code></pre>
+
+ <p>Then create the keystore file in the conf/ directory with the default password <code>james72laBalle</code>
+ <pre><code>
+$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
+ </code></pre>
+
+ <p>Second, modify deletedMessageVault.properties configuration file like an example at previous paragraph</p>
+
+ <p>Third, modify listeners.xml to configure DeletedMessageVaultHook by adding preDeletionHook section at previous paragraph</p>
+
+ <p>Fourth, We will create a local folder for holding data out of the container:</p>
+ <pre><code>
+mkdir var
+ </code></pre>
+
+ <p>Finally, starting a James Server by docker compose</p>
+ <p>Getting James docker-compose.yml</p>
+ <pre><code>
+$ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml
+ </code></pre>
+
+ <p>Add the following volumes for james service:</p>
+ <pre><code>
+volumes:
+ - $PWD/conf:/root/conf/
+ - $PWD/var:/root/var/
+ </code></pre>
+
+ <header class="major">
+ <h2><b>How to administrate Deleted Messages Vault</b></h2>
+ </header>
+
+ <p>
+ These are supported WebAdmin features on top of Deleted Messages Vault.
+ You can have a look at WebAdmin Deleted Messages Vault document at <a href="https://james.apache.org/server/manage-webadmin.html#Deleted_Messages_Vault">here</a>
+ </p>
+
+ <header class="major">
+ <h3><b>WebAdmin Deleted Messages Vault exporting</b></h3>
+ </header>
+
+ <p>
+ This part is a bit special to you, you are able to choose which exporting mechanism to be used. At the moment there are one available exporting mechanism
+ </p>
+ <ul>
+ <li><b>localFile</b>: This is a simple exporting mechanism while with an export request, it retrieves deleted mails from Deleted Messages Vault,
+ then store them as a zip file in local file system in James Server. Then sending a mail with the absolute path of exported file to the targeted mail address.</li>
+ </ul>
+ <p>
+ You can configure which kind of export mechanism to use in James by specifying <b>blob.export.implementation</b> in blobStore.properties configuration file.
+ E.g:
+ </p>
+ <pre><code>
+blob.export.implementation=localFile
+ </code></pre>
+
+ <p>
+ More details about configuration & example at <a href="/server/config-blob-expor.html">Blob Export Configuration</a>
+ </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>
diff --git a/src/homepage/howTo/imap-server.html b/src/homepage/howTo/imap-server.html
index 8459f4c..57c787e 100644
--- a/src/homepage/howTo/imap-server.html
+++ b/src/homepage/howTo/imap-server.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: howTo
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,232 +19,164 @@ layout: default
specific language governing permissions and limitations
under the License.
-->
-<link href="assets/css/lightbox.css" rel="stylesheet">
-<link href="assets/css/lity.min.css" rel="stylesheet" />
-<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>
-
- <!-- Header -->
- <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>
-
- <!-- Main -->
- <div id="main">
-
- <!-- Introduction -->
- <section id="intro" class="main special">
- <div class="">
- <div class="content align-left">
- <header class="major">
- <h1><b>Setting up an IMAP server</b></h1>
- </header>
-
- <p>
- This document will present how to set up a James server in order to serve as a personal IMAP + SMTP
- server. We will cover:
- </p>
-
- <ul>
- <li>DNS creation and MX record</li>
- <li>Server components description</li>
- <li>Generation of a custom keystore</li>
- <li>Starting James</li>
- <li>Basic James administration</li>
- <li>Additional features one might want to enable...</li>
- </ul>
-
- <p>
- This guide rely on the JPA Guice Docker image. To run it, one need to have docker installed.
- </p>
-
- <header class="major">
- <h2><b>DNS resolution</b></h2>
- </header>
-
- <p>
- Someone willing to send you an email will first have to discover which IP your mail server has.
- The way this is achieved is through MX (means Mail eXchange) DNS record.
- </p>
-
- <p>
- Imagine bob@domain.org sends a mail to alice@company.com. Bob will:
- </p>
-
- <ol>
- <li>Ask <code>company.com</code> DNS server its MX entries</li>
- <li><code>company.com</code> respond that it is <code>mx.company.com</code></li>
- <li>Bob resolves <code>mx.company.com</code> ip address...</li>
- <li>...and can establish a connection to <code>mx.company.com</code> to send an email to Alice</li>
- </ol>
-
- <p>All is needed is a MX entry in domain name resolution pointing to the future IP of your James server.</p>
-
- <header class="major">
- <h2><b>JAMES architecture</b></h2>
- </header>
-
- <p>JPA guice docker image relies on an embedded Derby database for storing data. Note that Apache Lucene library
- is used for email search. A mail queue is implemented on top of an embedded Apache ActiveMQ. Hence James do not need
- any external service for being running.
- </p>
-
- <img src="/images/guice-jpa-architecture-overview.png">
-
- <p>
- JPA guice offers the following protocols:
- </p>
-
- <ul class="no-padding">
- <li><b>SMTP</b> For receiving emails</li>
- <li><b>IMAP</b> For reading emails</li>
- <li><b><a href="http://james.apache.org/server/manage-webadmin.html">WebAdmin</a></b> is a REST API allowing you to manage Apache JAMES</li>
- </ul>
-
- <p>The following protocols are also available:</p>
-
- <ul class="no-padding">
- <li><b>LMTP</b> local version of SMTP</li>
- <li><b>POP3</b> For reading emails. Lacks tests</li>
- <li><b>JMX</b> is used by a <a href="http://james.apache.org/server/manage-cli.html">command line</a> for administrating Apache James</li>
- <li>And <a href="http://james.apache.org/server/feature-protocols.html">more</a>...</li>
- </ul>
-
- <header class="major">
- <h2><b>Generation of a custom keystore</b></h2>
- </header>
-
- <p>In order to maintain a good level of privacy and security, James is relying on TLS cryptography
- for securing exchanges. We thus need to generate our own personal keystore. Note that this guide do not
- cover generating a keystore from SSL certificates. A security exception might be configured on the Mail
- User Agent.</p>
-
- <p>In order to create a keystore, please run: <code>keytool -genkey -alias james -keyalg RSA -keystore /path/to/james/conf/keystore</code>.
- James is configured with a default password <code>james72laBalle</code> (used to read the keystore). However, we will be overriding the
- configuration of the docker image, so you can be defining your own.</p>
-
- <header class="major">
- <h2><b>Starting james</b></h2>
- </header>
-
- <p>We want to override the configuration of the docker image with a volume.</p>
-
- <p>First let's retrieve a valid configuration:</p>
-
- <pre><code>$ git clone https://github.com/apache/james-project
+
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Setting up an IMAP server</b></h1>
+ </header>
+
+ <p>
+ This document will present how to set up a James server in order to serve as a personal IMAP + SMTP
+ server. We will cover:
+ </p>
+
+ <ul>
+ <li>DNS creation and MX record</li>
+ <li>Server components description</li>
+ <li>Generation of a custom keystore</li>
+ <li>Starting James</li>
+ <li>Basic James administration</li>
+ <li>Additional features one might want to enable...</li>
+ </ul>
+
+ <p>
+ This guide rely on the JPA Guice Docker image. To run it, one need to have docker installed.
+ </p>
+
+ <header class="major">
+ <h2><b>DNS resolution</b></h2>
+ </header>
+
+ <p>
+ Someone willing to send you an email will first have to discover which IP your mail server has.
+ The way this is achieved is through MX (means Mail eXchange) DNS record.
+ </p>
+
+ <p>
+ Imagine bob@domain.org sends a mail to alice@company.com. Bob will:
+ </p>
+
+ <ol>
+ <li>Ask <code>company.com</code> DNS server its MX entries</li>
+ <li><code>company.com</code> respond that it is <code>mx.company.com</code></li>
+ <li>Bob resolves <code>mx.company.com</code> ip address...</li>
+ <li>...and can establish a connection to <code>mx.company.com</code> to send an email to Alice</li>
+ </ol>
+
+ <p>All is needed is a MX entry in domain name resolution pointing to the future IP of your James server.</p>
+
+ <header class="major">
+ <h2><b>JAMES architecture</b></h2>
+ </header>
+
+ <p>JPA guice docker image relies on an embedded Derby database for storing data. Note that Apache Lucene library
+ is used for email search. A mail queue is implemented on top of an embedded Apache ActiveMQ. Hence James do not need
+ any external service for being running.
+ </p>
+
+ <img src="/images/guice-jpa-architecture-overview.png">
+
+ <p>
+ JPA guice offers the following protocols:
+ </p>
+
+ <ul class="no-padding">
+ <li><b>SMTP</b> For receiving emails</li>
+ <li><b>IMAP</b> For reading emails</li>
+ <li><b><a href="http://james.apache.org/server/manage-webadmin.html">WebAdmin</a></b> is a REST API allowing you to manage Apache JAMES</li>
+ </ul>
+
+ <p>The following protocols are also available:</p>
+
+ <ul class="no-padding">
+ <li><b>LMTP</b> local version of SMTP</li>
+ <li><b>POP3</b> For reading emails. Lacks tests</li>
+ <li><b>JMX</b> is used by a <a href="http://james.apache.org/server/manage-cli.html">command line</a> for administrating Apache James</li>
+ <li>And <a href="http://james.apache.org/server/feature-protocols.html">more</a>...</li>
+ </ul>
+
+ <header class="major">
+ <h2><b>Generation of a custom keystore</b></h2>
+ </header>
+
+ <p>In order to maintain a good level of privacy and security, James is relying on TLS cryptography
+ for securing exchanges. We thus need to generate our own personal keystore. Note that this guide do not
+ cover generating a keystore from SSL certificates. A security exception might be configured on the Mail
+ User Agent.</p>
+
+ <p>In order to create a keystore, please run: <code>keytool -genkey -alias james -keyalg RSA -keystore /path/to/james/conf/keystore</code>.
+ James is configured with a default password <code>james72laBalle</code> (used to read the keystore). However, we will be overriding the
+ configuration of the docker image, so you can be defining your own.</p>
+
+ <header class="major">
+ <h2><b>Starting james</b></h2>
+ </header>
+
+ <p>We want to override the configuration of the docker image with a volume.</p>
+
+ <p>First let's retrieve a valid configuration:</p>
+
+ <pre><code>$ git clone https://github.com/apache/james-project
$ cp -rf james-project/dockerfiles/run/guice/jpa/destination/conf conf
$ mv keystore conf/keystore</code></pre>
- <p>Modify all protocol configuration files to match your keystore password (imapserver.xml, lmtpserver.xml, managesieveserver.xml, pop3server.xml, smtpserver.xml).</p>
+ <p>Modify all protocol configuration files to match your keystore password (imapserver.xml, lmtpserver.xml, managesieveserver.xml, pop3server.xml, smtpserver.xml).</p>
- <p>We will create a local folder for holding data out of the container:</p>
+ <p>We will create a local folder for holding data out of the container:</p>
- <pre><code>mkdir var</code></pre>
+ <pre><code>mkdir var</code></pre>
- <p>Then, let's start James:</p>
+ <p>Then, let's start James:</p>
- <pre><code>docker run \
- --name james_run \
- --port "25:25" --port "465:465" --port "587:587" \
- --port "143:143" --port "993:993" \
- --volume "$PWD/conf:/root/conf/" \
- --volume "$PWD/var:/root/var/" \
+ <pre><code>docker run \
+--name james_run \
+--port "25:25" --port "465:465" --port "587:587" \
+--port "143:143" --port "993:993" \
+--volume "$PWD/conf:/root/conf/" \
+--volume "$PWD/var:/root/var/" \
linagora/james-jpa-guice:latest</code></pre>
- <header class="major">
- <h2><b>Administrating James</b></h2>
- </header>
+ <header class="major">
+ <h2><b>Administrating James</b></h2>
+ </header>
- <p>We now have a running James server. We just need to tell him which users and domains it should be handling mails for.
- We will, in order to do this, use the command line:</p>
+ <p>We now have a running James server. We just need to tell him which users and domains it should be handling mails for.
+ We will, in order to do this, use the command line:</p>
- <pre><code>docker exec james_run java -jar /root/james-cli.jar AddDomain domain.tld
+ <pre><code>docker exec james_run java -jar /root/james-cli.jar AddDomain domain.tld
docker exec james_run java -jar /root/james-cli.jar AddUser user@domain.tld secretPassword</code></pre>
- <p>The command line client can be used for several other purposes like managing quota, setting addresses redirections, etc.</p>
+ <p>The command line client can be used for several other purposes like managing quota, setting addresses redirections, etc.</p>
- <header class="major">
- <h2><b>Additional features</b></h2>
- </header>
+ <header class="major">
+ <h2><b>Additional features</b></h2>
+ </header>
- <p>James is a large project with many features. You can go further and complete your installation with
- an <a href="http://james.apache.org/server/config-antispam.html">AntiSpam system</a>, or set up
- <a href="http://james.apache.org/server/metrics.html">metric display</a>, collect logs in ElasticSearch for a display in Kibana,
- and much more!</p>
+ <p>James is a large project with many features. You can go further and complete your installation with
+ an <a href="http://james.apache.org/server/config-antispam.html">AntiSpam system</a>, or set up
+ <a href="http://james.apache.org/server/metrics.html">metric display</a>, collect logs in ElasticSearch for a display in Kibana,
+ and much more!</p>
- <p>Also, James offers support for <a href="https://medium.com/linagora-engineering/installing-james-3-0-with-spf-verification-421b26b92f11">SPF</a>
- and DKIM standard, which increase the trust external people can get in your mail system.</p>
+ <p>Also, James offers support for <a href="https://medium.com/linagora-engineering/installing-james-3-0-with-spf-verification-421b26b92f11">SPF</a>
+ and DKIM standard, which increase the trust external people can get in your mail system.</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>
- <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-2018 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>
+ <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>
-<!-- Scripts -->
-<script src="assets/js/jquery.min.js"></script>
-<script src="assets/js/jquery.scrollex.min.js"></script>
-<script src="assets/js/jquery.scrolly.min.js"></script>
-<script src="assets/js/skel.min.js"></script>
-<script src="assets/js/util.js"></script>
-<script src="assets/js/lightbox.js"></script>
-<script src="assets/js/github-fetch.js"></script>
-<script src="assets/js/lity.min.js"></script>
-<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
-<script src="assets/js/main.js"></script>
diff --git a/src/homepage/howTo/index.html b/src/homepage/howTo/index.html
index c356ac8..b30ebc8 100644
--- a/src/homepage/howTo/index.html
+++ b/src/homepage/howTo/index.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: howTo
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,124 +19,67 @@ layout: default
specific language governing permissions and limitations
under the License.
-->
-<link href="assets/css/lightbox.css" rel="stylesheet">
-<link href="assets/css/lity.min.css" rel="stylesheet" />
-<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>
- <!-- Header -->
- <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>
+<!-- Main -->
+ <div id="main">
- <!-- Main -->
- <div id="main">
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content">
+ <header class="major">
+ <h2>James how to's...</h2>
+ </header>
+ <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
+ This section explains in detail how to achieve these cool features in a straightforward way.</p>
- <!-- Introduction -->
- <section id="intro" class="main special">
- <div class="">
- <div class="content">
- <header class="major">
- <h2>James how to's...</h2>
- </header>
- <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
- This section explains in detail how to achieve these cool features in a straightforward way.</p>
+ <a href="imap-server.html"
+ data-lightbox="james-schema"
+ data-title="Setting up an IMAP server"
+ alt="Setting up an IMAP server"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
+ </a>
+ <a href="spf.html"
+ data-lightbox="james-schema"
+ data-title="Configuring SPF"
+ alt="Configuring SPF"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
+ </a>
+ <a href="deleted-messages-vault.html"
+ data-lightbox="james-schema"
+ data-title="Deleted Messages Vault"
+ alt="Deleted Messages Vault"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
+ </a>
- <a href="mail-processing.html"
- data-lightbox="james-schema"
- data-title="Customized mail processing"
- alt="Customized mail processing"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="imap-server.html"
- data-lightbox="james-schema"
- data-title="Setting up an IMAP server"
- alt="Setting up an IMAP server"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="spf.html"
- data-lightbox="james-schema"
- data-title="Configuring SPF"
- alt="Configuring SPF"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="deleted-messages-vault.html"
- data-lightbox="james-schema"
- data-title="Deleted Messages Vault"
- alt="Deleted Messages Vault"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
- </a>
+ <header class="major">
+ <h2>Customize James</h2>
+ </header>
+ <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
+ <a href="mail-processing.html"
+ data-lightbox="james-schema"
+ data-title="Customized mail processing"
+ alt="Customized mail processing"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
+ </a>
+ <a href="custom-listeners.html"
+ data-lightbox="james-schema"
+ data-title="Configure Custom Listeners"
+ alt="Configure Custom Listeners"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
+ </a>
- <br/>
- <br/>
+ <br/>
+ <br/>
- </div>
</div>
- </section>
-
- </div>
- <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>
+ </div>
</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-2018 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>
-<!-- Scripts -->
-<script src="assets/js/jquery.min.js"></script>
-<script src="assets/js/jquery.scrollex.min.js"></script>
-<script src="assets/js/jquery.scrolly.min.js"></script>
-<script src="assets/js/skel.min.js"></script>
-<script src="assets/js/util.js"></script>
-<script src="assets/js/lightbox.js"></script>
-<script src="assets/js/github-fetch.js"></script>
-<script src="assets/js/lity.min.js"></script>
-<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
-<script src="assets/js/main.js"></script>
+ </div>
diff --git a/src/homepage/howTo/mail-processing.html b/src/homepage/howTo/mail-processing.html
index 1f10887..93dd971 100644
--- a/src/homepage/howTo/mail-processing.html
+++ b/src/homepage/howTo/mail-processing.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: howTo
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,269 +19,199 @@ layout: default
specific language governing permissions and limitations
under the License.
-->
-<link href="assets/css/lightbox.css" rel="stylesheet">
-<link href="assets/css/lity.min.css" rel="stylesheet" />
-<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>
-
- <!-- Header -->
- <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>
-
- <!-- Main -->
- <div id="main">
-
- <!-- Introduction -->
- <section id="intro" class="main special">
- <div class="">
- <div class="content align-left">
- <header class="major">
- <h1>How to customize mail processing</h1>
- </header>
- <header class="major">
- <h2><b>Mail processing component overview</b></h2>
- </header>
- <p class="align-left">At the heart of James lies the Mailet container, which allows mail processing. This is
- splitted into smaller units, with specific responsibilities:
-
- </p>
-
- <ul class="no-padding">
- <li><b>Mailets:</b> Are operations performed with the mail: modifying it, performing a side-effect, etc...</li>
- <li><b>Matchers:</b> Are per-recipient conditions for mailet executions</li>
- <li><b>Processors:</b> Are matcher/mailet pair execution threads</li>
- </ul>
- <p> Read <a href="/server/feature-mailetcontainer.html">this</a> for more explanations of mailet container concepts.</p>
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1>How to customize mail processing</h1>
+ </header>
+ <header class="major">
+ <h2><b>Mail processing component overview</b></h2>
+ </header>
+ <p class="align-left">At the heart of James lies the Mailet container, which allows mail processing. This is
+ splitted into smaller units, with specific responsibilities:
+
+ </p>
+
+ <ul class="no-padding">
+ <li><b>Mailets:</b> Are operations performed with the mail: modifying it, performing a side-effect, etc...</li>
+ <li><b>Matchers:</b> Are per-recipient conditions for mailet executions</li>
+ <li><b>Processors:</b> Are matcher/mailet pair execution threads</li>
+ </ul>
+
+ <p> Read <a href="/server/feature-mailetcontainer.html">this</a> for more explanations of mailet container concepts.</p>
- <p>Once we define the mailet container content through the <a href="/server/config-mailetcontainer.html">mailetcontailer.xml</a> file.
- Hence, we can arrange James standard components listed <a href="/server/dev-provided-mailets.html">here</a> to achieve basic logic. But what if our goals are more
- complex? What if we need our own processing components?</p>
+ <p>Once we define the mailet container content through the <a href="/server/config-mailetcontainer.html">mailetcontailer.xml</a> file.
+ Hence, we can arrange James standard components listed <a href="/server/dev-provided-mailets.html">here</a> to achieve basic logic. But what if our goals are more
+ complex? What if we need our own processing components?</p>
- <p>This page will propose a 'hands on practice' how-to using James 3.3.0. We will implement a custom mailet and a custom matcher,
- then deploy it in a James server.</p>
+ <p>This page will propose a 'hands on practice' how-to using James 3.3.0. We will implement a custom mailet and a custom matcher,
+ then deploy it in a James server.</p>
- <p>We need to choose our use case. We will, when a mail is delayed over one day, write a mail to the original sender
- to inform him about the delay, say that we are sorry, and send him a promotion code...<pre></pre></p>
+ <p>We need to choose our use case. We will, when a mail is delayed over one day, write a mail to the original sender
+ to inform him about the delay, say that we are sorry, and send him a promotion code...<pre></pre></p>
- <header class="major">
- <h2><b>Writing custom mailets and matchers</b></h2>
- </header>
+ <header class="major">
+ <h2><b>Writing custom mailets and matchers</b></h2>
+ </header>
- <p>None of the matchers and mailets available in James allows us to implement what we want. We will have to
- write our own mailet and matcher in a separated maven project depending on James Mailet API.</p>
+ <p>None of the matchers and mailets available in James allows us to implement what we want. We will have to
+ write our own mailet and matcher in a separated maven project depending on James Mailet API.</p>
- <p>We will write a <b>IsDelayedForMoreThan</b> matcher with a configurable delay. If the Sent Date of incoming emails is older than specified delay, then the emails
- should be matched (return all mail recipients). Otherwise, we just return an empty list of recipients.</p>
+ <p>We will write a <b>IsDelayedForMoreThan</b> matcher with a configurable delay. If the Sent Date of incoming emails is older than specified delay, then the emails
+ should be matched (return all mail recipients). Otherwise, we just return an empty list of recipients.</p>
- <p>To ease our Job, we can rely on the <b>org.apache.james.apache-mailet-base</b> maven project, which provides us a <b>GenericMatcher</b> that we can extend.</p>
+ <p>To ease our Job, we can rely on the <b>org.apache.james.apache-mailet-base</b> maven project, which provides us a <b>GenericMatcher</b> that we can extend.</p>
- <p>Here is the dependency:</p>
+ <p>Here is the dependency:</p>
- <pre><code><dependency>
- <groupId>org.apache.james</groupId>
- <artifactId>apache-mailet-base</artifactId>
+ <pre><code><dependency>
+<groupId>org.apache.james</groupId>
+<artifactId>apache-mailet-base</artifactId>
</dependency></code></pre>
- <p>The main method of a matcher is the <b>match</b> method:</p>
+ <p>The main method of a matcher is the <b>match</b> method:</p>
- <pre><code>Collection<MailAddress> match(Mail mail) throws MessagingException;</code></pre>
+ <pre><code>Collection<MailAddress> match(Mail mail) throws MessagingException;</code></pre>
- <p>For us, it becomes, with <b>maxDelay</b> being previously configured:</p>
+ <p>For us, it becomes, with <b>maxDelay</b> being previously configured:</p>
- <pre><code> private final Clock clock;
- private Duration maxDelay;
+ <pre><code> private final Clock clock;
+private Duration maxDelay;
- @Override
- public Collection<MailAddress> match(Mail mail) throws MessagingException {
- Date sentDate = mail.getMessage().getSentDate();
+@Override
+public Collection<MailAddress> match(Mail mail) throws MessagingException {
+ Date sentDate = mail.getMessage().getSentDate();
- if (clock.instant().isAfter(sentDate.toInstant().plusMillis(maxDelay.toMillis()))) {
- return ImmutableList.copyOf(mail.getRecipients());
- }
- return ImmutableList.of();
- }</code></pre>
+ if (clock.instant().isAfter(sentDate.toInstant().plusMillis(maxDelay.toMillis()))) {
+ return ImmutableList.copyOf(mail.getRecipients());
+ }
+ return ImmutableList.of();
+}</code></pre>
- <p><b>GenericMatcher</b> exposes us the condition that had been configured. We will use it to compute <b>maxDelay</b>.
- We can do it in the <b>init()</b> method exposed by the generic matcher:</p>
+ <p><b>GenericMatcher</b> exposes us the condition that had been configured. We will use it to compute <b>maxDelay</b>.
+ We can do it in the <b>init()</b> method exposed by the generic matcher:</p>
- <pre><code>
- public static final TimeConverter.Unit DEFAULT_UNIT = TimeConverter.Unit.HOURS;
+ <pre><code>
+public static final TimeConverter.Unit DEFAULT_UNIT = TimeConverter.Unit.HOURS;
- @Override
- public void init() {
- String condition = getCondition();
- maxDelay = Duration.ofMillis(TimeConverter.getMilliSeconds(condition, DEFAULT_UNIT));
- }</code></pre>
+@Override
+public void init() {
+ String condition = getCondition();
+ maxDelay = Duration.ofMillis(TimeConverter.getMilliSeconds(condition, DEFAULT_UNIT));
+}</code></pre>
- <p>Now, let's take a look at the <b>SendPromotionCode</b> mailet. Of course, we want to write a generic mailet
- with a configurable reason (why are we sending the promotion code). To keep things simple, only one promotion
- code will be used, and will be written in the configuration. We can here also simply extend the
- <b>GenericMailet</b> helper class.</p>
+ <p>Now, let's take a look at the <b>SendPromotionCode</b> mailet. Of course, we want to write a generic mailet
+ with a configurable reason (why are we sending the promotion code). To keep things simple, only one promotion
+ code will be used, and will be written in the configuration. We can here also simply extend the
+ <b>GenericMailet</b> helper class.</p>
- <p>The main method of a mailet is the <b>service</b> method:</p>
+ <p>The main method of a mailet is the <b>service</b> method:</p>
- <pre><code>void service(Mail mail) throws MessagingException</code></pre>
+ <pre><code>void service(Mail mail) throws MessagingException</code></pre>
- <p>For us, it becomes, with <b>reason</b> and <b>promotionCode</b> being previously configured:</p>
+ <p>For us, it becomes, with <b>reason</b> and <b>promotionCode</b> being previously configured:</p>
- <pre><code> public static final boolean REPLY_TO_SENDER_ONLY = false;
+ <pre><code> public static final boolean REPLY_TO_SENDER_ONLY = false;
- private String reason;
- private String promotionCode;
+private String reason;
+private String promotionCode;
- @Override
- public void service(Mail mail) throws MessagingException {
- MimeMessage response = (MimeMessage) mail.getMessage()
- .reply(REPLY_TO_SENDER_ONLY);
+@Override
+public void service(Mail mail) throws MessagingException {
+ MimeMessage response = (MimeMessage) mail.getMessage()
+ .reply(REPLY_TO_SENDER_ONLY);
- response.setText(reason + "\n\n" +
- "Here is the following promotion code that you can use on your next order: " + promotionCode);
+ response.setText(reason + "\n\n" +
+ "Here is the following promotion code that you can use on your next order: " + promotionCode);
- MailAddress sender = getMailetContext().getPostmaster();
- ImmutableList<MailAddress> recipients = ImmutableList.of(mail.getSender());
+ MailAddress sender = getMailetContext().getPostmaster();
+ ImmutableList<MailAddress> recipients = ImmutableList.of(mail.getSender());
- getMailetContext()
- .sendMail(sender, recipients, response);
- }</code></pre>
+ getMailetContext()
+ .sendMail(sender, recipients, response);
+}</code></pre>
- <p>Note that we can interact with the mail server through the mailet context for sending mails, knowing postmaster, etc...</p>
+ <p>Note that we can interact with the mail server through the mailet context for sending mails, knowing postmaster, etc...</p>
- <p><b>GenericMailet</b> exposes us the 'init parameters' that had been configured for this mailet. We will
- use it to retrieve <b>reason</b> and <b>promotionCode</b>.
- We can do it in the <b>init()</b> method exposed by the generic mailet:</p>
+ <p><b>GenericMailet</b> exposes us the 'init parameters' that had been configured for this mailet. We will
+ use it to retrieve <b>reason</b> and <b>promotionCode</b>.
+ We can do it in the <b>init()</b> method exposed by the generic mailet:</p>
- <pre><code> @Override
- public void init() throws MessagingException {
- reason = getInitParameter("reason");
- promotionCode = getInitParameter("promotionCode");
+ <pre><code> @Override
+public void init() throws MessagingException {
+ reason = getInitParameter("reason");
+ promotionCode = getInitParameter("promotionCode");
- if (Strings.isNullOrEmpty(reason)) {
- throw new MessagingException("'reason' is compulsory");
- }
- if (Strings.isNullOrEmpty(promotionCode)) {
- throw new MessagingException("'promotionCode' is compulsory");
- }
- }</code></pre>
+ if (Strings.isNullOrEmpty(reason)) {
+ throw new MessagingException("'reason' is compulsory");
+ }
+ if (Strings.isNullOrEmpty(promotionCode)) {
+ throw new MessagingException("'promotionCode' is compulsory");
+ }
+}</code></pre>
- <p>You can retrieve the sources of this mini-project on <a href="https://github.com/apache/james-project/tree/master/examples/custom-mailets">GitHub</a></p>
+ <p>You can retrieve the sources of this mini-project on <a href="https://github.com/apache/james-project/tree/master/examples/custom-mailets">GitHub</a></p>
- <header class="major">
- <h2><b>Loading custom mailets with James</b></h2>
- </header>
+ <header class="major">
+ <h2><b>Loading custom mailets with James</b></h2>
+ </header>
- <p>Now is the time we will run James with our awesome matcher and mailet configured.</p>
+ <p>Now is the time we will run James with our awesome matcher and mailet configured.</p>
- <p>First, we will need to compile our project with <code>mvn clean install</code>. A jar will be outputted in the target directory.</p>
+ <p>First, we will need to compile our project with <code>mvn clean install</code>. A jar will be outputted in the target directory.</p>
- <p>Then, we will write the <code>mailetcontainer.xml</code> file expressing the logic we want:</p>
+ <p>Then, we will write the <code>mailetcontainer.xml</code> file expressing the logic we want:</p>
- <pre><code>
+ <pre><code>
<mailetcontainer enableJmx="true">
- <context>
- <postmaster>postmaster@james.minet.net</postmaster>
- </context>
-
- <spooler>
- <threads>20</threads>
- </spooler>
-
- <processors>
- <processor state="root" enableJmx="true">
- <mailet match="All" class="PostmasterAlias"/>
- <mailet match="org.apache.james.examples.custom.mailets.IsDelayedForMoreThan=1 day"
- class="org.apache.james.examples.custom.mailets.SendPromotionCode">
- <reason>Your email had been delayed for a long time. Because we are sorry about it, please find the
- following promotion code.</reason>
- <promotionCode>1542-2563-5469</promotionCode>
- </mailet>
- <!-- Rest of the configuration -->
- </processor>
-
- <!-- Other processors -->
- </processors>
+<context>
+ <postmaster>postmaster@james.minet.net</postmaster>
+</context>
+
+<spooler>
+ <threads>20</threads>
+</spooler>
+
+<processors>
+ <processor state="root" enableJmx="true">
+ <mailet match="All" class="PostmasterAlias"/>
+ <mailet match="org.apache.james.examples.custom.mailets.IsDelayedForMoreThan=1 day"
+ class="org.apache.james.examples.custom.mailets.SendPromotionCode">
+ <reason>Your email had been delayed for a long time. Because we are sorry about it, please find the
+ following promotion code.</reason>
+ <promotionCode>1542-2563-5469</promotionCode>
+ </mailet>
+ <!-- Rest of the configuration -->
+ </processor>
+
+ <!-- Other processors -->
+</processors>
</mailetcontainer></code></pre>
- <p>Finally, we will start a James server using that. We will rely on docker default image for simplicity.
- We need to be using the <b>mailetcontainer.xml</b> configuration that we had been writing and position
- the jar in the <b>extensions-jars</b> folder (specific to guice). This can be achieved with the following command:</p>
-
- <pre><code>docker run -p "25:25" -p "143:143" \
- -v "$PWD/src/main/resources/mailetcontainer.xml:/root/conf/mailetcontainer.xml" \
- -v "$PWD/target/custom-mailets-3.3.0-SNAPSHOT.jar:/root/extensions-jars/custom-mailets.jar" \
- linagora/james-jpa-sample:3.3.0</code></pre>
-
- </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>
- <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-2018 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>
+ <p>Finally, we will start a James server using that. We will rely on docker default image for simplicity.
+ We need to be using the <b>mailetcontainer.xml</b> configuration that we had been writing and position
+ the jar in the <b>extensions-jars</b> folder (specific to guice). This can be achieved with the following command:</p>
-<!-- Scripts -->
-<script src="assets/js/jquery.min.js"></script>
-<script src="assets/js/jquery.scrollex.min.js"></script>
-<script src="assets/js/jquery.scrolly.min.js"></script>
-<script src="assets/js/skel.min.js"></script>
-<script src="assets/js/util.js"></script>
-<script src="assets/js/lightbox.js"></script>
-<script src="assets/js/github-fetch.js"></script>
-<script src="assets/js/lity.min.js"></script>
-<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
-<script src="assets/js/main.js"></script>
+ <pre><code>docker run -p "25:25" -p "143:143" \
+ -v "$PWD/src/main/resources/mailetcontainer.xml:/root/conf/mailetcontainer.xml" \
+ -v "$PWD/target/custom-mailets-3.3.0-SNAPSHOT.jar:/root/extensions-jars/custom-mailets.jar" \
+ linagora/james-jpa-sample:3.3.0</code></pre>
+ </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>
diff --git a/src/homepage/howTo/spf.html b/src/homepage/howTo/spf.html
index 023c3a1..ab2fa74 100644
--- a/src/homepage/howTo/spf.html
+++ b/src/homepage/howTo/spf.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: howTo
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,215 +19,146 @@ layout: default
specific language governing permissions and limitations
under the License.
-->
-<link href="assets/css/lightbox.css" rel="stylesheet">
-<link href="assets/css/lity.min.css" rel="stylesheet" />
-<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>
-
- <!-- Header -->
- <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>
-
- <!-- Main -->
- <div id="main">
-
- <!-- Introduction -->
- <section id="intro" class="main special">
- <div class="">
- <div class="content align-left">
- <header class="major">
- <h1><b>Setting up SPF</b></h1>
- </header>
-
- <p>
- You just finished installing a <a href="imap-server.html">James IMAP server</a> and wonder how to
- gain trust for it?
- </p>
-
- <p>
- The Sender Policy Framework (SPF) is an open standard specifying a technical method to prevent
- sender address forgery. It might help you to do this.
- </p>
-
- <p>
- More precisely, SPF protects the envelope sender address, which is used for the delivery of messages.
- It allows the owner of a domain to specify their mail sending policy, e.g. which mail servers they
- use to send emails from their domain.
- </p>
-
- <p>
- To correctly configure SPF for your domain, you need to answer the following questions:
- </p>
-
- <ul>
- <li><b>From what server or servers will email from my domain originate?</b> In our case, we only
- want our James Server to be able to send emails from our domain.</li>
- <li><b>How do you want illegitimate email to be handled?</b> <code>-all</code> is an SPF fail and
- usually means dropping such emails, whereas <code>~all</code> is an SPF softfail and traditionally
- means accepting but marking them.</li>
- </ul>
-
- <p>
- Therefore, we add the following DNS records to our DNS zone file:
- </p>
-
- <pre><code>@ IN TXT “v=spf1 +a:james.test-domain.com -all”
+
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Setting up SPF</b></h1>
+ </header>
+
+ <p>
+ You just finished installing a <a href="imap-server.html">James IMAP server</a> and wonder how to
+ gain trust for it?
+ </p>
+
+ <p>
+ The Sender Policy Framework (SPF) is an open standard specifying a technical method to prevent
+ sender address forgery. It might help you to do this.
+ </p>
+
+ <p>
+ More precisely, SPF protects the envelope sender address, which is used for the delivery of messages.
+ It allows the owner of a domain to specify their mail sending policy, e.g. which mail servers they
+ use to send emails from their domain.
+ </p>
+
+ <p>
+ To correctly configure SPF for your domain, you need to answer the following questions:
+ </p>
+
+ <ul>
+ <li><b>From what server or servers will email from my domain originate?</b> In our case, we only
+ want our James Server to be able to send emails from our domain.</li>
+ <li><b>How do you want illegitimate email to be handled?</b> <code>-all</code> is an SPF fail and
+ usually means dropping such emails, whereas <code>~all</code> is an SPF softfail and traditionally
+ means accepting but marking them.</li>
+ </ul>
+
+ <p>
+ Therefore, we add the following DNS records to our DNS zone file:
+ </p>
+
+ <pre><code>@ IN TXT “v=spf1 +a:james.test-domain.com -all”
@ IN SPF “v=spf1 +a:james.test-domain.com -all”</code></pre>
- <p>That way other mail servers know only <i>james.test-domain.com</i> can send mails for <i>test-domain.com</i>.</p>
+ <p>That way other mail servers know only <i>james.test-domain.com</i> can send mails for <i>test-domain.com</i>.</p>
- <header class="major">
- <h1><b>Verifying SPF for incoming emails</b></h1>
- </header>
+ <header class="major">
+ <h1><b>Verifying SPF for incoming emails</b></h1>
+ </header>
- <p>
- Now we will see how to verify SPF records of incoming emails. For this we can customize mail processing,
- and specify actions upon SPF record validity. For introducing these components, James relies on the
- <a href="https://james.apache.org/jspf/">JSPF</a> library.
- </p>
+ <p>
+ Now we will see how to verify SPF records of incoming emails. For this we can customize mail processing,
+ and specify actions upon SPF record validity. For introducing these components, James relies on the
+ <a href="https://james.apache.org/jspf/">JSPF</a> library.
+ </p>
- <p>We just need to edit the <code>mailetcontainer.xml</code> configuration file as follow:</p>
+ <p>We just need to edit the <code>mailetcontainer.xml</code> configuration file as follow:</p>
- <p>We are going to create a new processor called <b>SPFProcessor</b>. It will handle emails after
- the <b>root</b> processor but before the <b>transport</b> processor. Moreover, we do not need to
- perform a SPF check or take a decision if the sender is authenticated or is a local user, because
- we already trust him.
+ <p>We are going to create a new processor called <b>SPFProcessor</b>. It will handle emails after
+ the <b>root</b> processor but before the <b>transport</b> processor. Moreover, we do not need to
+ perform a SPF check or take a decision if the sender is authenticated or is a local user, because
+ we already trust him.
- In all other cases, we add a SPF header using the <b>SPF</b> mailet. Then we need to take a decision
- about incoming emails. We use the <b>HasMailAttributeWithValue</b> matcher which has seven possible
- values to handle in the case of SPF: <b>permerror</b>, <b>temperror</b>, <b>none</b>, <b>pass</b>,
- <b>neutral</b>, <b>fail</b> and <b>softfail</b>. What action you choose for each of these values
- depends on what you want to do. In our case, we redirect SPF errors and fails to the <b>error</b>
- processor, whereas all other cases lead directly to the <b>transport</b> processor for further
- normal processing. We are rather tolerant since we authorize <b>softfails</b>.</p>
+ In all other cases, we add a SPF header using the <b>SPF</b> mailet. Then we need to take a decision
+ about incoming emails. We use the <b>HasMailAttributeWithValue</b> matcher which has seven possible
+ values to handle in the case of SPF: <b>permerror</b>, <b>temperror</b>, <b>none</b>, <b>pass</b>,
+ <b>neutral</b>, <b>fail</b> and <b>softfail</b>. What action you choose for each of these values
+ depends on what you want to do. In our case, we redirect SPF errors and fails to the <b>error</b>
+ processor, whereas all other cases lead directly to the <b>transport</b> processor for further
+ normal processing. We are rather tolerant since we authorize <b>softfails</b>.</p>
- <p>For example:</p>
+ <p>For example:</p>
- <pre><code>[...]
+ <pre><code>[...]
<processors>
- <processor state="root" enableJmx="true">
- <mailet match="All" class="PostmasterAlias"/>
- <mailet match="RelayLimit=30" class="Null"/>
- <mailet match="All" class="ToProcessor">
- <processor>SPFProcessor</processor>
- </mailet>
- </processor>
-
- <processor state="error" enableJmx="true">
- [...]
- </processor>
-
- <processor state="SPFProcessor">
- <mailet match="SenderIsLocal" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="SMTPAuthSuccessful" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="All" class="SPF">
- <addHeader>true</addHeader>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, permerror" class="ToProcessor">
- <processor>error</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, temperror" class="ToProcessor">
- <processor>error</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, none" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, pass" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, neutral" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, fail" class="ToProcessor">
- <processor>error</processor>
- </mailet>
- <mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, softfail" class="ToProcessor">
- <processor>transport</processor>
- </mailet>
- <mailet match="All" class="LogMessage">
- <headers>true</headers>
- <body>false</body>
- <comment>Unknown SPF result</comment>
- </mailet>
- </processor>
+<processor state="root" enableJmx="true">
+<mailet match="All" class="PostmasterAlias"/>
+<mailet match="RelayLimit=30" class="Null"/>
+<mailet match="All" class="ToProcessor">
+ <processor>SPFProcessor</processor>
+</mailet>
+</processor>
+
+<processor state="error" enableJmx="true">
+[...]
+</processor>
+
+<processor state="SPFProcessor">
+<mailet match="SenderIsLocal" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="SMTPAuthSuccessful" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="All" class="SPF">
+ <addHeader>true</addHeader>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, permerror" class="ToProcessor">
+ <processor>error</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, temperror" class="ToProcessor">
+ <processor>error</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, none" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, pass" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, neutral" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, fail" class="ToProcessor">
+ <processor>error</processor>
+</mailet>
+<mailet match="HasMailAttributeWithValue=org.apache.james.transport.mailets.spf.result, softfail" class="ToProcessor">
+ <processor>transport</processor>
+</mailet>
+<mailet match="All" class="LogMessage">
+ <headers>true</headers>
+ <body>false</body>
+ <comment>Unknown SPF result</comment>
+</mailet>
+</processor>
[...]</code></pre>
- </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>
- <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-2018 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>
+ <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>
-<!-- Scripts -->
-<script src="assets/js/jquery.min.js"></script>
-<script src="assets/js/jquery.scrollex.min.js"></script>
-<script src="assets/js/jquery.scrolly.min.js"></script>
-<script src="assets/js/skel.min.js"></script>
-<script src="assets/js/util.js"></script>
-<script src="assets/js/lightbox.js"></script>
-<script src="assets/js/github-fetch.js"></script>
-<script src="assets/js/lity.min.js"></script>
-<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
-<script src="assets/js/main.js"></script>
+</div>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org