RESTful API for on-premise SMTP server for relaying emails

Xeams API offers a robust way of sending emails and managing administrative tasks using RESTful API that is based on OpenAPI standards v3.0. You can use this API if you have a Xeams server installed on your premise. This feature is NOT available in Xeams Cloud.

API Reference
Created by Swagger UI

Prerequisites

  • On-Premise Xeams version 9.3 or above.
  • Enterprise license with at least 20 users.

Getting Started

Use the following steps to create an API Key and a Secret before sending requests.

  • Click Home/Plugin
  • Click the Manage button for Xeams API
  • Provide a friendly name for the key and grant desired permission
  • The following page will display a randomly generated API Key and secret. You will need both of these values when connecting through the API. The value for the Secret field can never be displayed again. Therefore, save it in safe place. You will have to create another key in case these values are lost.

Sending API Key and Secret

You will need to send the API Key and Secret with every request you make, which can be done in two ways:

  1. Parameter in the URL: Append the request URL with ?auth-key=YourKey&secret=YourSecret
  2. Basic Authentication: Send these values using the BASIC Authentication scheme in an HTTP request.

Sending Requests

The following examples sends a request to /info, which is a convinient method for testing connectivity and authentication with your Xeams Server. It uses JZ5UMPFLSQXZ1YRAQXLUI1XC6Z4ZZN0S for API Key, and Xjtg1ctJprsEmfbjZ7g8 for the secret. You will need to replace these strings with actual values generated by your Xeams.

You must use HTTPS in a production environment. The examples you see below use HTTP for simplicity.

Example 1 - Passing auth-key and secret URL's query string

curl -X 'GET' \
  "http://localhost:5272/api/info?auth-key=JZ5UMPFLSQXZ1YRAQXLUI1XC6Z4ZZN0S&secret=Xjtg1ctJprsEmfbjZ7g8" \
  -H "accept: application/json"

Example 2 - Using BASIC Authentication

curl -X GET "http://localhost:7860/api/info" \
	-H "accept: application/json" \
	-u "JZ5UMPFLSQXZ1YRAQXLUI1XC6Z4ZZN0S:Xjtg1ctJprsEmfbjZ7g8"

Response

Response will be returned in JSON formatted string. In this case, it will look like: 
{
    "code": 200,
    "description": "9.3 - build: 6321"
}

Example 3 - Sending Email

This example sends an email to Xeams, which then relays this message to a foreign domain. This example demonstrates the following features:

  • Sending an email containing the body in HTML
  • Contains an attachment. The content field is truncated in this example.
  • Ability to use a server-side template, identified by the template-id field, which formats the outgoing email.

An HTTP POST method is required when sending emails. The screenshot below demonstrates sending a request using PostMan

A few important points to note when sending emails are:

  • Content-type for every POST request must be a application/json
  • You can optionally enclose your HTML body with preconfigured templates identified by the template-id field.
  • A sample POST request is displayed below. 
{
  "from-email": "user@your-company.com",
  "from-name": "John Doe",
  "recipient-fn": "Bob",
  "recipient-ln": "Smith",
  "to": "user@example.com,user2@example.com",
  "subject": "This is a test message",
  "cc": "cc_user@example.com",
  "bcc": "bcc_user@example.com",
  "template-id" : 1, /* Specified the template for this message. */
  "is_html": true,
  "body": "This is HTML version of the message.",
  "custom_headers": {
    "List-Unsubscribe": "",
    "X-Entity-Ref-ID": "123",
    "Tracking-Id": "888884433",
    "reply-to": "alternative-email@domain.com"
  },
  "attachments": [
    {
      "content": "iVBORw0KGgoAAN11SQpl2E1KEkUIS7FaMDTbK...truncated",
      "name": "email.gif",
      "type": "image/gif",
      "inline": false,
      "content-id": "does not matter"
    }
  ]
}

Email Templates

When sending emails in HTML, you can wrap your body in predefined templates. You are encouraged to modify existing templates or add as many templates as you like, provided following rules are applied.

  • Templates are stored in $INSTALL_DIR/EmailTemplates, where $INSTALL_DIR refers to the folder where Xeams is installed.
  • The file name of every template must start with a number followed by a dash. For example, 5-My Template.htm
  • The number signifies a template ID, corresponding to the template-id field in the JSON request. If two files are found with the same number, Xeams will pick the first available.
  • If the template-id field is missing, no template will be applied.

Administrative Tasks

In addition to sending emails, you can use this API to perform certain administrative tasks, provided your API key has been granted permission. For example, you can:

  • Add/modify users
  • Add/modify domains
  • Add/modify distribution lists
  • Restart Xeams

Refer to the API Reference for details.

Generating Client-Side Code

Xeams API is based on OpenAPI 3.0 standards. Therefore, you can use the code generation tool on Swagger to create client-side code for your favorite language.

Instructions