This is a scratchpad to help capture answers that should go into document (FAQ, etc...). These can be considered pending documentation that as the notes are moved into CVS, they can be removed from this page.

What does the sendmail "SMART_HOST" concept map to in James?

You can use the RemoteDelivery mailet to either send messages using normal MX lookups, or have them deliver all emails to a given server. You do this by setting the <gateway> parameter in the RemoteDelivery mailet. If you want some emails to go through normal MX lookup delivery and some mail to all go to a particular mail server, you can configure two instances of RemoteDelivery, one to do normal MX lookup delivery and one to direct all mail to your other server. (be sure the two instances are using different <outgoing> spools.)

You can also emulate sendmail's "local relay" and "mail hub" by using the remote delivery mailet, as described above, with the "HostIs=localhost" and "HostIsLocal" matchers respectively to forward all local mail to another machine.

See also SmartOrSecondaryHost for details.

Is there a web-based or GUI based interface to the James admin system?

No, but there is an rmi-interface in the proposals directory that could be used as the basis of one.

Why does it take 30 hours to get a bounce message?

If there is a network issue (DNS, temporary exception on remote server, network outage), James (by default) is set to retry 15 times every 2 hours. If it is a permanent error (like no user or mailbox is full), then the bounce will come back immediately.

You can change how frequently and how many times it retries by modifying the RemoteDelivery mailet configuration (

Where do I make these configuration changes/where is config.xml?

First, you have to start James at least once, which will setup many files for James. The file that contains most changes is config.xml, and this is in apps/james/conf/config.xml.

How do I deploy my custom mailets?

See CustomMailetPackages for details.

Why does James accept all messages instead of rejecting emails during the SMTP session?

The biggest reason is because it allows remote users to "harvest" email addresses. The SMTP client could try numerous email addresses, and if they're rejected, they know not to send this anymore. By waiting until spool processing, it means there are also more options on how to handle it and otherwise greatly slows any harvesting efforts.

Also, it gives admins much more flexibility as there is a growing set of matchers and mailets that can be used during spool processing. There is discussion to build an API to support SMTP session communication, but the development community is still leaning towards leaving the processing. Also, the expense of accepting the messages and processing them is not significantly more expensive unless there is a DOS type scenario (which can be handled via other methods).

The SMTP server may also add some rules to disconnect after an excessive number of errors to help reduce harvesting techniques.

There is a longer, biased explanation of these issues in Serge's NoFastFail wiki page.

Is it ok to disable RemoteAddrNotInNetwork?

NO!!! Under no case should you disable this. Even if this is an internal-only mail server, we still recommend leaving this in and just setting the appropriate network addresses. This is the single most important configuration setting to prevent relaying.

In James v2.2 or later, you could substitute the authorized addresses support in the SMTP handler for RemoteAddrNotInNetwork. But you must have one or the other.

What databases does James support

We have generalized SQL and support overriding this with special SQL for certain databases. This includes MySQL, Oracle, MS SQL, SAP DB, PostgreSQL, and Hypersonic. Sometimes with new releases it takes time to have all database calls updated, but the database queries do not change frequently.

If you have another database you use or would like to use, we welcome any patches to the sqlResources.xml file.

How can I use multiple domains?

James does not include the ability to easily manage multiple domains, but there are some ways to make it happen. First, SMTP and POP3 do not support the virtual hosting concept in that all pop3 mailboxes must have a unique username across all domains.

Read more about how people have used James to handle multiple domains in the VirtualHostGuide.

Why can't James deliver emails to other servers?

Ten times out of ten, this is because you did not tell James what DNS servers to use. You need to edit the config.xml file to set the DNS servers. Instructions are in config.xml.

Actually I just found another reason: In the transport processor the default RemoteAddrNotInNetwork= was causing mail sent to be marked as spam even though I was sending from the same machine. It turns out that the localhost was identifying with an IPv6 address, so changing it to RemoteAddrNotInNetwork=,0:0:0:0:0:0:0:1 did the trick. -- Torbjörn Gannholm

Why does James need it's own DNS servers? Can't it just use my machine's DNS like every other program?

Mail servers uses "MX" DNS records to determine where to deliver messages, while most other programs (email clients, web browsers, etc...) use only "A" and "CNAME". "MX" records have extra information including a priority level and can have a hostname point to multiple mail servers.

James is looking to upgrade its DNS library that will try to detect the underlying DNS settings on your machine. The reliability of this approach is not conclusive, but it may allow you to avoid setting this.

I'm running James at, but I can't seem to deliver emails to postmaster@ What's wrong?

First, IP addresses in email addresses must be surrounded by [], e.g., postmaster@[]. However, mail serves (MTAs) are often bad at handling IP routing, so we'd recommend that you use an email address with an explicity hostname.

Is anybody running James in production?

Yes!! The James code base has been run in production since 1999 when it was originally donated to Apache. It has gone through many revisions and achieved a healthy downloads, averaging between 6000 and 8000 downloads per month in 2001 and 2002. In 2003, this is up to 12,000 downloads per month. The 2.1 release includes significant performance and robustness improvements as well.

How can I change the logging

The logging channels are configured in the server.xml (environment.xml) file (next to the config.xml). James uses Avalon's logging capabilities, and you can learn more about how to change log files, rotations or otherwise configure logging from reading the javadocs for FileTargetFactory.

See also LogRotation.

How can I (re-)process emails that are in the error processor?

If you are using a file store, you can simply move the file-pairs from one directory to the other, e.g., move them from the errors directory to the spool directory, and restart James. If this was a DB, you could just do an update statement on the repository_name.

Note: make sure you get both files at once, otherwise you risk losing them as James will delete an orphaned file if it comes across one. (you could copy and then delete to be safe).

How can I improve outgoing message performance?

This question is also related to the Why aren't my other messages going out when James is timing out on a dead host? question.

RemoteDelivery defaults to using a single delivery thread, but it is easy (I would say desirable) to add more delivery threads, using the <deliveryThreads> element. See RemoteDelivery Parameters for details.

Why can't KMail connect to James through SSL/TLS?

As of version 1.5 (KDE 3.1), KMail tries to use the default port 465 to test the SSL/TLS connection with a SMTP mail server, even if you specify a different port number.

If you plan to use the SSL/TLS feature of James, be sure to stick to the IANA standards. It means, use port 465 instead of 25 for the SSL/TLS-enabled SMTP port number of James.

Can I run James in a J2EE application server such as JBoss, WebLogic or Websphere?

You can use the JMXLauncher in Phoenix to start James in any app server that supports JMX, JBoss, WebLogic and Websphere included. Last time I looked, the JMXLauncher was not available in a released version of Phoenix so if this is still the case you'll need to get the Phoenix sources and compile yourself.

I have successfully run James in JBoss and WebLogic.

James and IPv6

If you are using IPv6, you may need to change the addresses passed to Matchers in config.xml, e.g.,


because localhost may resolve as the IPv6 address 0:0:0:0:0:0:0:1 instead of

What about allowing developers to process messages during the SMTP session?

To date we have elected to accept all and then process for the following reasons:

1. It makes mail processing synchronous instead of asynchronous, so when your mail server is busy, you become unable to accept both good and bad messages.

2. The bandwidth-preservation argument is not very compeling. Virus scanners are licensed in messages per hour, so unless you are very rich or have a 9600 baud modem, you'll probably not have an issue. Spam rejection is a bit more compeling, but given that the MAIL FROM and RCPT TO commands can be 100% forged, you can't do much spam rejection without receiving the message, thus not saving you much.

3. It takes bounces by *your* mail server and puts the burden of writing a good explanation on the *remote* mail server.

4. Denial-of-service is probably the most compeling reason to do something like this, but these don't need to be programmatic, and some standard conf file settings could handle most needs.

My mail is being blocked because my server is on a dynamic IP address

If your message server is assigned a dynamic IP address, e.g., you are using dial-up, DSL, or cable modem in a DHCP pool, there is every likelihood that your e-mail will be blocked. This is because spammers often use banks of computers attached to DHCP pools to obfuscate their origin. Accordingly, many SMTP servers are being configured to block mail from DHCP pools. Only your ISP's mail server(s) will accept mail sent directly from your dynamic IP address.

So how do you use James to send mail? You configure RemoteDelivery to use the SMTP server provided by your ISP as a gateway:

         <mailet match="All" class="RemoteDelivery">
            <outgoing> file://var/mail/outgoing/ </outgoing>
            <delayTime> 21600000 </delayTime> 
            <maxRetries> 5 </maxRetries> 
            <deliveryThreads> 5 </deliveryThreads> 

Your ISP will accept the e-mail, and others will accept e-mail from your ISP.

Endless spool loops, when using the Forward, Redirect etc. mailets

If you forget that the forwarded message reenters the root processor, you can easily create endless loops in the spool manager.

I can deliver to most hosts just fine, but Hotmail is returning 554.

It turns out James was using 'localhost' as the outgoing SMTP helloName. James will use one of two sources for the outgoing SMTP helloName:

  1. The <helloName> defined by the <smtpserver> block for the SMTP server.

  2. One of the defined <servernames> in no guaranteed order.

The code prefers to use the <smtpserver> setting for the outgoing name unless the SMTP server is disabled. If <helloName autodetect="true"> is used (the default), the SMTP server will use the machine name associated by the OS networking layer with the computer (Windows users know this as the "computer name"; *nix users as the host name).

A bug in the code prior to v2.2 meant that in some rare cases the outgoing SMTP hello name was not properly detected.

I'm getting the following exception: BindException: Address in use: JVM_Bind

Check that you don't have another email server running. One way to check is on that computer (before you try to start James), telnet to ports 25 and 110 and see if you can connect. If you can, then an email server is already running.

I'm using MySQL with James and cannot send attachments greater than around 750k or so.

You need to edit your my.conf file (try /etc/my.cnf or look for my-medium.cnf in the installation dirs of MySQL). You need to set the max_allowed_packet variable, for example:

set-variable = max_allowed_packet=12M

Nota Bene: It is a quirk of Connector/J v2 that the maximum size allowed for a JBDC request is only 75% of the value allowed for the max_allowed_packet.

I'm getting OutOfMemoryExceptions from large emails.

You'll want to increase the heap size of your JVM. The PHOENIX_JVM_OPTS environment variable is used to specify additional options to the JVM. To increase the heap size, for example, you could add -Xmx128m (or larger), e.g.,

Windows: set PHOENIX_JVM_OPTS=-Xmx128m
Bash: export PHOENIX_JVM_OPTS=-Xmx128m

A more complex example would be:

export PHOENIX_JVM_OPTS='-Xrunhprof:heap=sites,depth=9 -server'

which configures heap profiling and enables Hotspot Server.

What could cause "No Object DCH for MIME type multipart/mixed"?

Check your classpath for other copies of mail.jar and activation.jar.

Send mail from CGI

The documentation explains how to configure 'sendmail' on Linux. I'm running Windows XP and have no idea what to do. All I want is to be able to send mail that comes from a cgi-script on my webserver.

Find or write a simple mail client. There is one in Jakarta Commons.

You may check into BLAT! to perform this function on Windows machines. There is a port of "FormMail" (Perl CGI) available at to use it.

Do I have to use Sendmail with James

No, in fact we think you should avoid sendmail at all costs.

Can I make config changes without restarting?

No, not at this time