Foxway HTTP SMTP Proxy API

Daniel Grindelid -

The Foxway HTTP SMTP Proxy API can run either as a Servlet in a Servlet container or from the command line. The Servlet configuration is suitable when going for a more persistent setup and where a Servlet container also is already available. The command line version is intended to be used when testing or including in other java projects.

Usage

The proxy exposes a GET and a POST method. The GET doesn't do anything else than returning a status saying that there is nothing to GET. The POST method accepts a payload largely inherited from the Mandrill API and should be identical to the API exposed by the Foxway AppCloud Mail API, but currently only support basic features.

Running from the command line

Requirements: Java Runtime Environment 7 or later (Download).

The command line version comes with a configuration file (expected to be named config.txt and live in the same folder as the JAR file.) Update the configuration with appropriate values for mail server and any other.

Sample config.txt:

[http_server]
host=localhost
port=8587
auth=false
auth_user=admin
auth_password=admin

[smtp_server]
host=smtp.mailserver.local
port=587
username=user
password=password1
SSL=false
default_from=hello@example.com
default_to=admin@example.com

[logging]
log_file=log.txt
log_size=5000000
backup_count=5

The configuration file is divided into three sections: http_server, smtp_server and logging.

http_server

host: The interface that the host should listen to. If only testing locally this can be set to localhost, otherwise set to 0.0.0.0 or the used host’s host name.

port: The port to be used for the api

auth: Enable or disable BASIC AUTH. If set to `true` the username and password in auth_user and auth_password is used when signing in.

smtp_server

host: The SMTP server to be used for sending the mails

port: The port used on the SMTP server.

username: The username (if any) when signing in to the SMTP server

password: The password to the provided user

SSL: Set to true if the connection should be configured to use SSL

default_from: Used as from address if no from address is provided

default_to: Used as recipient if no recipient is provided

logging

log_file: Path and name of the log file written by the service

log_size: The size limitation of the log file before rotating

backup_count: The number of log files to keep


How to start the server

Start the server by running this from a command prompt:

  java -jar foxwayhttpsmtpproxy.jar

Troubleshooting

If you experience any problems, please make sure you follow the installation instructions above. Here's a list of suggestions of what to do if it still doesn't work:

  • Look for errors in the log file specified in config.txt

Running as a Servlet

Requirements: Java 7 or later (Download). A servlet container supporting Servlet 2.4.

The Foxway HTTP SMTP Proxy API can be deployed in an external server, such as Tomcat, Jetty, GlassFish or Geronimo. It comes packaged as a standard Java web application, foxwayhttpsmtpproxy.war, which can be easily deployed in any compatible servlet container. The most commonly used server is Tomcat, and the rest of this section describes how to install or upgrade Foxway HTTP SMTP Proxy API on a Tomcat server.

Stop Tomcat if it's running.
Remove these files and directories if they exist:

  • TOMCAT_HOME/webapps/foxwayhttpsmtpproxy.war
  • TOMCAT_HOME/webapps/foxwayhttpsmtpproxy
  • TOMCAT_HOME/work

Copy the file foxwayhttpsmtpproxy.war to TOMCAT_HOME/webapps.

Start Tomcat.

Point your web browser to http://localhost/foxwayhttpsmtpproxy (or http://localhost:8080/foxwayhttpsmtpproxy if you installed Tomcat on port 8080.)

Configuration

The Servlet configuration lives in web.xml under WEB-INF in the foxwayhttpsmtpproxy folder expanded in the Servlet container.

The following init-params is expected to be present in the web.xml file:


<init-param>
<param-name>smtp_host</param-name>
<param-value>smtp.host.com</param-value>
</init-param>
<init-param>
<param-name>smtp_port</param-name>
<param-value>587</param-value>
</init-param>
<init-param>
<param-name>smtp_username</param-name>
<param-value>user</param-value>
</init-param>
<init-param>
<param-name>smtp_password</param-name>
<param-value>password</param-value>
</init-param>
<init-param>
<param-name>smtp_use_ssl</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>default_from</param-name>
<param-value>hello@example.com</param-value>
</init-param>
<init-param>
<param-name>default_to</param-name>
<param-value>admin@example.com</param-value>
</init-param>

smtp_host: The SMTP server to be used for sending the mails

smtp_port: The port used on the SMTP server.

smtp_username: The username (if any) when signing in to the SMTP server

smtp_password: The password to the provided user

smtp_use_ssl: Set to true if the connection should be configured to use SSL

default_from: Used as from address if no from address is provided

default_to: Used as recipient if no recipient is provided

Notes

If you installed Tomcat as a Windows Service, you can start and stop it from the service manager: Control Panel > Administrative Tools > Services.
TOMCAT_HOME refers to the directory in which you installed Tomcat. On Windows this is normally C:\Program Files\Apache Software Foundation\Tomcat 7

Troubleshooting

If you experience any problems, please make sure you follow the installation instructions above. Here's a list of suggestions of what to do if it still doesn't work:

  • Restart Tomcat.
  • Reinstall Foxway HTTP SMTP Proxy API.
  • Upgrade to the latest Tomcat version (at least if you're using Tomcat 7.0 or earlier).
  • Look for errors in the Tomcat logs, TOMCAT_HOME/logs.

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.