Documentation for the SEG REST API

This article applies to:

• Trustwave SEG 8.0 and above
• REST API

Question:

• Is there any documentation for the REST API?
• What functions are available through the REST API?

Information:

SEG 8.0 and above exposes a REST API for management functions.

This API provides all email administration functions, and a limited set of configuration functions.

You can use the API to:

• View and act on messages in folders
• Manage SQM users and configuration
• Commit configuration
• Force SpamCensor update
• Update user groups and members
• Query service and processing statistics
• Query DMARC data

The API cannot be used to manage rules and settings.

The API is a HTTPS web interface on the Array Manager server (port 19006 by default).

Security:

In MailMarshal (SEG) 10.X, the API is secured using Bearer tokens derived from Management Console credentials. Windows ACLs are not used. For details, see the MailMarshal (SEG) 10 API Handler listing attached to this article.

• Even when you use NTLM to secure the Management Console, you must use the local MailMarshal credentials (not Windows accounts) to access the API.

In SEG 8.X, the API is secured using Windows credentials and implements the same account permissions as the Console and Configurator.

• To use the API, the account must have the permission Log on as a batch job. Administrator accounts have this permission by default. You can grant this permission to other accounts using Group Policy.

Calling Applications:

• You can use an application such as Postman to connect to the API for testing purposes.
• You can use any scripting language to develop production uses for the API.

Caution:

• The REST API is used internally by SEG and SPE. It is exposed for use by customers who have appropriate understanding and skills.
• Documentation is limited to the API definitions and this article.
• Trustwave does not provide detailed usage documentation or support for applications that call the API. Development of any such application is at the customer's risk and responsibility.
• Test on a test system before deploying to production, and ensure automatic configuration backups are enabled.
• Data entered through the API may not be fully validated by SEG. The calling application is responsible to ensure that data is valid and correctly formatted.
  • In particular, string data such as object names is only validated in the Configurator.
  • See the section Known validation items for details.
• API functions are subject to change. Applications should check the interface version or product version before making other calls.

To enable and configure the REST API, use the SEG Server Tool.

• To retrieve a list of available functions in the installed version of the API, when logged on to the Array Manager server, use the following URL:
  https://localhost:19006/seg/api/debug/handlers/
  • The response includes descriptions and definitions of each available call to the API.
  • Attached to this article is a formatted copy of this listing updated for SEG 8.2.3, and another updated for a recent version of MailMarshal (SEG) 10.X.
    • Note that the available functions in these releases differ, and future releases are also likely to differ.
  • The API can be made available from other locations as with any website, depending on firewall settings. Ensure that this interface is secured against abuse.
• Input and output is in JSON format.
• Query Parameters are sent as a http querystring. The parameter names are case sensitive.
• Variable data in querystrings MUST be URL Encoded. For example, a semi-colon ; must be represented as %3B
• Times (integers) are Unix epoch timestamps. The minimum value is 0 and the maximum value is 2147483647. For testing, you can convert times using many free online services. For production, cast the date/time to this format programmatically.
• Where the API requires a processMessageKey, this is a JSON object containing the following items that can be retrieved from results of findmessage (all items required):
  • blockNumber, edition, folderId, messageName, recipient, serverId, timeLogged

Simple GET examples:

Send a GET request to return information.

• Get list of servers
  https://localhost:19006/seg/api/services/servers
  • Returns information like the "servers" list in the Configurator, including the server ID
• Get receiver statistics for server 1
  https://localhost:19006/seg/api/console/overview/1/receiver
  • Returns similar statistics to the Console Servers  | Receiver  window.
• Get list of groups
  https://localhost:19006/seg/api/groups
• Get list of members in a group
  https://localhost:19006/seg/api/groups/3/members
  • Returns details of each user in the group.

Simple POST examples:

Add an email address member to a group

• The call is defined as:
  

   {  "description": "Add member to a group   Post data fields: memberType(int), memberGroupId(int),      memberData(string), touchDate(int)      GroupMemberType: 0 - group, 1 - email, 2 - wildcard",  "method": "POST",  "url": "^groups/usermaintained/(?<groupid>[0-9]+)/members/$" }

• The URL to add a member to Group 3 is:
  https://localhost:19006/seg/api/groups/usermaintained/3/members
• Send a POST request with JSON formatted body, such as:
  

  {      "memberType":1, "memberData":"coo@example.com">", "touchDate":0}

• Returns a JSON message (member added, or member already exists)
  
  

Kill messages from the Sender queue by recipient, sender, or subject

• The call is defined as:
  

   {  "description": "Kill messages current queued/being delivered by Sender   Post data fields: sender(string,regular expression),     recipient(string,regular expression),      subject(string,regular expression),     speCustomerId(int) - at least one of these is required     bNotify(bool, optional)",  "method": "POST",  "url": "^console/sender/message/killex/(?<serverid>[0-9+]/" }

• The URL to kill messages on server 2 is:
  https://localhost:19006/seg/api/console/sender/message/killex/2/
• Send a POST request with JSON formatted body. For instance, to kill messages to gmail.com and return a notification to the senders:
  

  {      "recipient":".*@gmail\\.com$","bNotify":true}

• Note the double-backslash required as the escape character in JSON representation of regular expressions
• Returns a JSON message (number of messages deleted and server number)

Search Mail History (similar to Console search)

• The call is defined as:
  

   {  "description": "Finds message by specified parameters   Post data fields: startTime(int, required), endTime(int, required),     folderId(int), messageName(str), actionType(int), classification(int),
      fromUser(str), fromDomain(str),toOrFrom(bool), toUser(str), 
      toDomain(str), minSize(int), maxSize(int), subject(str), 
      searchHistory(bool), forwards(bool), blockNumber(int64), 
      searchBlankSubject(bool), direction(int)
  Query parameters: maxRows(int, required)",  "method": "POST",  "url": "^quarantine/findmessage/$"}

• The URL to return up to 5 results is:
  https://localhost:19006/seg/api/quarantine/findmessage/?maxRows=5
• Send a POST request with JSON formatted body. You must include a start and end time as Unix time integers. You must include the querystring parameter maxRows.
• Parameters are case sensitive.
• For instance, to find messages sent from gmail.com, from the earliest to the last available time, use this body:
  

  {      "startTime":0 , "endTime":2147483647 ,"fromDomain":"gmail.com"  }

• By default the search only finds messages quarantined in folders. To include history records like "Undeliverable" results, add "searchHistory":true
• To understand the other available parameters, see the Search feature in the Console.
• To find folder and classification IDs, look them up using other REST calls
• Returns a JSON array (details of the matching messages)

Simple PATCH example using a JSON array:

Update IP group membership with addition and deletion in the same call

• The call is defined as:
  

  {  "description": "Add membership delta information to an IP group   Patch data fields:     add(array of objects with fields:            ipAddressStart(string), cidr(int),            ipAddressEnd(string, required only when cidr is 0),            name(string), description(string)),     remove(array of objects with fields:            ipAddressStart(string), cidr(int), ipAddressEnd(string))",  "method": "PATCH",  "url": "^ipgroups/(?<groupid>[0-9]+)/delta/$" }

• The URL to change membership of Group 15 is:
  https://localhost:19006/seg/api/ipgroups/15/delta
• Send a PATCH request with JSON formatted body, such as:
  

  {"add":[  {"ipAddressStart":"10.1.1.0","cidr":28,   "name":"Address Item 1","description":"Ten"},  {"ipAddressStart":"12.1.1.0","cidr":28,   "name":"Address Item 2","description":"12"}],"remove":[  {"ipAddressStart":"10.1.2.3","ipAddressEnd":"10.1.2.3","cidr":32}]}

• Item names and IP ranges must be unique.
• If any one of the operations cannot be performed, the entire call is cancelled
• Returns a JSON message (group updated, or member to add already exists, or member to remove does not exist)
• Note that for this call both Add and Remove sections are required. However either can be completely blank []

Known validation items

• Group names and IP group item entry names must not contain any of the following characters:
  ( ) / \ ; .
  Names using these characters are accepted by the API and do not cause problems with processing. However if you edit an item in the Configurator, you must remove the disallowed characters from the name before saving it.
• Quarantine message find commands require a start time and end time, as well as a value for the maxRows parameter. If any of these are missing, no rows are returned.