This was created on June 11, 2003 and is still being confirmed by new users. If this doesn't work for you, please let us know at server-user@james.apache.org.

If you edit this, and please do if you've useful changes, please check the numeric references. For example, the steps related to the DNS servers reference each other to help make sure that users understand what they need to do.


This page was written to help new users get started using James as quickly as possible.

  1. Download the latest stable 2.x release from http://james.apache.org.

  2. Extract the gz or zip file to a local directory (probably the root of your c drive in windows, or /opt/ on linux).
  3. Start bin/run.sh (unix) or bin\run.bat (windows) You will see something like the following:

    Using PHOENIX_HOME:   D:\James\james-2.1.3
    Using PHOENIX_TMPDIR: D:\James\james-2.1.3\temp
    Using JAVA_HOME:      c:\programming\java14
    Phoenix 4.0.1
    James 2.1.3
    Remote Manager Service started plain:4555
    POP3 Service started plain:110
    SMTP Service started plain:25
    NNTP Service started plain:119
    Fetch POP Disabled 

    On Unix platforms, bin/run.sh runs James in the console. To stop it, hit Ctrl-C. Alternatively you can use bin/phoenix.sh, which gives you sysinit functions such as start, stop, restart, and check.

  4. Kill the process (either do kill or ctrl-c or whatever you want). Starting James once was necessary to extract its directory structure and expose the configuration files to edit.
  5. Determine the DNS server to use. On Windows, type ipconfig /all and look for the DNS servers. On Unix, look at /etc/resolv.conf. You will need this information in step #9.

  6. Determine your local IP address for reference. On Windows, run ipconfig to see your IP Address. On Unix, run /sbin/ifconfig and look for your inet addr.

  7. Check the DNS configuration of the domain you want James to handle using http://www.dnsreport.com. If you want to handle email for foobar.com, put that domain name in the DNS Report field. On the report, you will want to check the MX record section to make sure the MX records point to the IP address you determined in the previous step, and that everything else about your domain's MX passes.

  8. Edit apps/james/SAR-INF/config.xml. Look over a section called <servernames> and put the domain you want to accept messages for within <servername> elements, e.g.,

      <servername> foobar.com </servername>
    Be sure you do not edit the instructional part of the conf file.
  9. Continue editing apps/james/SAR-INF/config.xml and look for a section called <dnsserver>. Put the DNS servers (from step #5 above) there, e.g.,:

        <server> </server>
        <server> </server>
      <authoritative> false </authoritative>
  10. Start James again using bin/run.sh or bin\run.bat

  11. Create a test user:

    # telnet localhost 4555
    JAMES Remote Administration Tool 2.2.0
    Please enter your login and password
    Login id:
    Welcome root. HELP for a list of commands
    adduser testuser password
    User testuser added
    Connection closed by foreign host.
  12. Send mail to your test user

    # telnet localhost 25
    Connected to localhost.
    Escape character is '^]'.
    220 hostname SMTP Server (JAMES SMTP Server 2.2.0) ready Mon, 20 Feb 2006 14:31:33 -0500 (EST)
    ehlo yourEmailAddressDomain.com
    250 hostname Hello yourEmailAddressDomain.com (hostname [])
    mail from: <morgan@yourEmailAddressDomain.com>
    250 Sender <morgan@yourEmailAddressDomain.com> OK
    rcpt to: <testuser@JAMESServerConfigSetting.com>
    250 Recipient <testuser@JAMESServersConfigSetting.com> OK
    354 Ok Send data ending with <CRLF>.<CRLF>
    subject: test to testuser at JAMESServersConfigSetting.com
    250 Message received
    221 hostname Service closing transmission channel
    Connection closed by foreign host.
  13. Have a look at the store to see if your testuser got the message:

    # cd james-2.2.0/apps/james/var/mail
    # ls inboxes/testuser
    # ls inboxes/testuser
    # more inboxes/testuser/4D61696C313134303436333937353538352D38.Repository.FileStreamStore
    Return-Path: <morgan@yourEmailAddressDomain.com>
    Received: from hostname ([])
              by hostname (JAMES SMTP Server 2.2.0) with SMTP ID 498
              for <testuser@JAMESServersConfigSetting.com>;
              Mon, 20 Feb 2006 14:32:54 -0500 (EST)
    subject: test to testuser at JAMESServersConfigSetting.com
    Date: Mon, 20 Feb 2006 14:32:54 -0500 (EST)
    From: morgan@yourEmailAddressDomain.com
    Delivered-To: testuser@JAMESServersConfigSetting.com
    Content-Transfer-Encoding: 7bit
    Content-Type: text/plain; charset=us-ascii
    Mime-Version: 1.0
    Message-ID: <18306724.1140463975582.JavaMail.root@hostname>
    JAMES does not print errors by default when a user is invalid, it puts the message into james-2.2.0/apps/james/var/mail/address-error
  14. To relay email for your local subnet only, without authentication, make the following changes, you need to edit apps/james/SAR-INF/config.xml. Look for the following default line <authorizedAddresses></authorizedAddresses>. Change this to contain your internal network:

    Either of the above will allow the internal network of with a subnet mask of to relay mail through JAMES without autentication.
  15. To test if you can now send email to the internet via JAMES, telnet to the JAMES server on port 25, and do a manual email test:

    # telnet james-server 25
    Connected to james-server.
    Escape character is '^]'.
    220 james-server SMTP Server (JAMES SMTP Server 2.3.1) ready Mon, 17 Sep 2007 21:31:00 -0700 (PDT)
    ehlo foo.com
    250-mailmaster Hello foo.com ( [])
    mail from:<user@localdomain.com>
    250 2.1.0 Sender <user@localdomain.com> OK
    rcpt to:<some-user@gmail.com>
    250 2.1.5 Recipient <some-user@gmail.com> OK
    354 Ok Send data ending with <CRLF>.<CRLF>
    subject:  test to some-user via JAMES
    This is a test from user@localdomain.com via james to the internet. 
    .   <---- Period (.) on a line by itself is the end of message indicator
    250 2.6.0 Message received
    ^]  <--- CNTL-] to quit from the telnet session
    telnet> quit

Note: From the default config.xml: <mailet match="RemoteAddrNotInNetwork=" class="ToProcessor"> <processor> relay-denied </processor> <notice>550 - Requested action not taken: relaying denied</notice> </mailet>

The above will bounce anything that isn't from localhost with a relay denied message. If you change the to the appropriate network, James will bounce anything outside of that network, but happily relay otherwise.

TOWRITE: How to test James is working for you. (use an external mail account to send a message to and from. need to create a local account too, maybe add a local IP address to use as the sender).

TOWRITE: Discuss possible errors...

  1. dynamic IP address issues
  2. ISP blocking outgoing port 25
  3. Email address with IP address instead of a domain name (possible workarounds)
  4. Messages going to spam because of sender's IP address (James catching as relay)
  5. Messages not getting accepted because your IP address/server is considered a relay.
  6. Another server already running preventing ports from binding.

Newbie might help also...

James can be used as a useful developer's tool when developing complex dynamic emails. By configuring James to catch absolutely every email that you forward to it and then pointing Mozilla Thunderbird or Outlook Express at the email, you can see exactly what your emails look like. See how you can setup James as a catchall.

JamesQuickstart (last edited 2012-07-03 01:40:43 by 91-204)