LUXSCI API v2 · 2020. 11. 20. · 6 LuxSci API v2: Mechanics luxsci.com Keyword Value custom1...

luxsci.com Last Updated: , 2021 for LuxSci v2021.2.4

LUXSCI API v2 Account Functions

by Erik Kangas, PhD

www.luxsci.com

http://www.luxsci.com/

2

LuxSci API v2: Mechanics

luxsci.com luxsci.com

TABLE OF CONTENTS

OVERVIEW ...................................................... 3

Account API Access Controls ...................... 3

LuxSci Secure Marketing Requests ............ 4

User Management Requests......................... 4 Get User Report ............................................... 5

Delete User ...................................................... 7

Update User Settings..................................... 7 Rename User ................................................. 10

Create User .................................................... 11

Domain Management Requests ................. 13 Create Domain ............................................... 13

Delete Domain ............................................... 14

Update Domain .............................................. 15

Get Domains Report ...................................... 17

Get Domain Details ........................................ 18

DKIM Requests ............................................. 19 Create DKIM .................................................. 19

Delete DKIM ................................................... 20

Get DKIM Report............................................ 20

Get DKIM Details ........................................... 21

Email Suppression ....................................... 22 Create Suppression ....................................... 22

Delete Suppression ........................................ 23

Get Suppression ............................................ 23

Email Alias Management Requests ........... 24 Create Alias .................................................... 24

Update Alias ................................................... 26

Delete Alias ................................................... 27 Get Aliases Report ......................................... 28

Get Alias Details ............................................ 29

SecureForm Management ........................... 30 Get SecureForm List ...................................... 30

Get SecureForm ............................................ 33

Get SecureForm Database Rows.................. 35

Get SecureForm Database Row ................... 37

Delete SecureForm Database Row ............... 38

Get SecureForm Database File ..................... 39

Delete SecureForm Database File ................ 40

SecureSend NameSpace Management ..... 41 Create/Update SecureSend User .................. 41

Change SecureSend User Password ............ 43

Get SecureSend User Single Sign-On Link .. 44

Get SecureSend User List ............................. 45

Reports .......................................................... 46 Report Querying and Results:

Commonalities ............................................... 47

Report: Email Sent ......................................... 48

Report: Email Delivery Status ........................ 53

Report: Email URL Clicks .............................. 58

Report: Email Opens...................................... 62

Report: SMTP Login Failures / Rejections .... 65

Report: Email Feed Back Loops .................... 66

Servers .......................................................... 68 List of All Servers ........................................... 68

Servers Status ............................................... 69

3



OVERVIEW

The “account” API scope allows your API client to access manage users, domains, email aliases, and

other account-level properties. Some user management tasks would be performed using “user” scope

(e.g. changing a user’s password); account-scope commands are more administrative and include

commands that would not be appropriate for a user to perform him/herself. You can access

commands in account scope:

• An API Integration whose “scope” is set to “account” (or higher) and where you have enabled

access control for the groups of account-level commands that you wish to perform.

Note that API credentials with account scope (or higher) do not need additional usernames or

passwords to perform commands. You must protect your API keys, as compromised keys will allow

others to perform any of the commands permitted to your API Integration. We also recommend that

you permit only specific IP addresses to use your API credentials.

All account requests have API URLS that start with:

/perl/v2/api/account/[ID]

where “ID” is the account unique ID number of the account with respect to which the command will

apply.

Account API Access Controls

The account API scope has a number of access controls that govern which commands your API is

allowed to perform. None of these commands is enabled by default – so your API can only execute

API commands that you have explicitly opted into. This table lists the available account- scope API

Access controls. As more commands are added in the future, they will either fall naturally into one of

these existing access groups, or new access groups will be added to cover them. Your API Interface

should not gain significant additional system access or control when new commands are added to the

API in the future; you will need to explicitly opt into use of any new functionality, should you decide

that your API client requires it.

4



Account-Scope Access Control Notes

General

User Scope

“Permit user-level commands without username and

password”

This allows your API Integration to perform user-scope

commands on allowed users without also supplying their

usernames and passwords.

Upgrades

“Permit auto-upgrades as needed to fulfill requests” Allows

the system to automatically upgrade your account, if needed,

in order to perform API commands such as “add user”.

Manage Domains

Permit domain management commands such as get domain

details, add domain, delete domain, update domain, manage

DKIM.

Manage Aliases Permit alias management commands such as get alias

reports, add aliases, delete alias.

User

Add Users Create new users

Modify Users Change user settings

Enable/Disable/Delete Delete users, disable users, enable users

LuxSci Secure Marketing Requests

The API calls for LuxSci Secure Marketing are at the account scope. However, there are so many of

them, that we have placed their documentation into a separate API Guide. See the document “LuxSci

Marketer API Functions” for their definitions.

User Management Requests

All user-management API requests use URLs of the form:

/perl/api/v2/account/[account id]/users/[username]...

where “username” is the login email address of the user in question. This “username” can also be just

the unique numerical ID of the user.

5



Get User Report

Return an array of information about all users matching your query request.

Request Method GET

Access Required User Settings: Read access

Request URL /perl/api/v2/account/[account id]/users

Request Query String See below

Request Body none

Success Response See below

Request Query String

The Request query string can contain any or all of the following keywords parameters to refine the

search. If all are omitted, the report will include information about all users in the account. In all cases,

any users protected from API access will not be included in the report.

Keyword Data Type Description

status Enum Value ‘enabled’ – return only active/enabled users.

Value ‘disabled’ – return only disabled users.

domain String Domain name in your account. If supplied, only users in this

domain will be returned.

younger_than Integer Return only users created less than this number of days ago.

older_than Integer Return only users created more than this number of days ago.

JSON Response

The successful response will be an array of objects, one for each matching user in your account. Each

user object returned will have the following keywords / values:

Keyword Value

city City

company Company / organization

contact Full name. E.g. “John Smith”

country Country

created Date and time this user was created (YYYY-MM-DD HH:MM:SS in GMT)

6



Keyword Value

custom1 Custom field #1



disk_quota Floating point limit on the user’s total disk space usage. In gigabytes (1 GB = 1000 MB). A value of “-1” signifies that the user does not have a disk usage limit.

disk_usage Floating point value for the user’s current (last measured) total disk space usage.

In gigabytes (1 GB = 1000 MB)

email1 Primary email address

email2 Alternate email address

fax FAX number

flags Array. Lists which of the following flags, if any, are set on this user:

• poor_password – User must change his/her password on the next login to the Web Interface

• can_autodelete – User account can be auto-deleted if the user has not logged in in a long time

uid Unique user ID (integer).

last_access_ date

Date Time the user last logged into any of WebMail, POP, IMAP, or SMTP (not updated real time). If the user has never logged in, this should be the same as the “created” date time. (YYYY-MM-DD HH:MM:SS in GMT)

modified Date and time this user was last modfiied (YYYY-MM-DD HH:MM:SS in GMT)

phone1 Primary contact phone number

phone2 Alternate contact phone number

services Array. Lists which of the following services the user has permission to use:

• pop – POP3 access to email

• imap – IMAP4 access to email

• smtp – SMTP for sending email

• spam – Basic Spam and Virus Filtering

• ftp – FTP and/or SFTP access

• website – permission to login to the Web Interface

state State/Province

status One of ‘enabled’ or ‘disabled’

street1 Street address (line 1)

street2 Street address (line 2)

user user name (e.g. [email protected])

zip Zip / postal code

7



Delete User

Delete the user from the system. This eliminates all the user’s data, history, web/ftp files and email.

After this command is complete, there will no longer be any record that the user existed.

This command cannot be undone.

Note that some users cannot be deleted in this way. For example, any user with “account

management” permission cannot be deleted. Other users may not be able to be deleted if there are

things in your account (e.g. web sites) that are still owned by them. You will receive an error if you try

to delete a user that is not currently deletable.

Note that deletion of a user does not downgrade your account. Please contact billing for account

downgrade requests.

Request Method DELETE

Access Required Enable / Disable / Delete Users

Request URL /perl/api/v2/account/[account id]/users/[username]

Request Query String none

Request Body none

Success Response nothing extra

Example (cookie omitted)

DELETE https://rest.luxsci.com/perl/api/v2/account/49721/users/[email protected]

HTTP/1.1 200 OK

Content-Type: application/json

{“auth”: [omitted],”success”:1}

Update User Settings

Change one or more properties of the user.

Request Method PUT

Access Required Account: Modify users (unless otherwise stated, below)

Request URL /perl/api/v2/account/[account id]/users/[username]

8




Request Body See below

Success Response none

JSON Request Body

The Request body can contain any or all of the following keywords. Each one changes a property of

the user. Keywords that are omitted will not cause any changes to the user’s settings.

Note that users with account administration access cannot be updated using this API command;

attempts to update them will result in an error.


add_service service_name Enable the specified service for the user. Valid service names include:

• “pop” – POP3 access to email

• “imap” – IMAP4 access to email

• “smtp” – SMTP for sending email

• “spam” – Basic Spam and Virus Filtering

• “ftp” – FTP and/or SFTP access

• “website” – permission to login to the Web Interface

FTP service can only be added to users in accounts with web server access.

If your account does not have enough licenses to add the requested service to the user, then the request will error out unless you have “Permit auto-upgrades as needed to fulfill request” enabled in your API Interface access control settings; in that case, your account will be upgraded and charged for the added licenses.

copy_ preferences_ from

User Name Pass the user name of another user in this account (e.g. “[email protected]”). Web Interface preferences will be copied from that user into the API target user (items like time zone, language, date and time formatting preferences, some WebMail interface preferences, etc.).

disable Integer If a “1” is passed, then the user will be disabled. Disabling a user simply prevents the user from logging into any services. It does not affect the user’s data and it does not block incoming email. This action is performed by temporarily changing the user’s password to a random string.

Requires access: “Account: Enable/Disable/Delete users”

mailto:[email protected]

9



Only currently-enabled users can be disabled.

disk_quota Floating Point Set a new hard total disk quota for this user. The value passed should be in Gigabytes. E.g. a value of 0.5 would set the limit to 500 MB. A value of zero is not permitted. A negative value will clear the disk quota ... resulting in the user no longer having a disk space limit (which is the default for all users).

Disk space is measured hourly. If the user’s individual disk usage (the sum of all disk space used by email, web, ftp, WebAides, etc.) exceeds his/her disk space quota, then many services will be explicitly disabled and incoming email will bounce. Since the disk usage is only checked hourly, it is possible that the user’s disk space usage will exceed the quota before the user’s account is suspended.

enable Integer If a “1” is passed, then the user will be re-enabled. Requires access: “Account: Enable/Disable/Delete users”

Only currently-disabled users can be enabled.

remove_flag flag_name Remove a flag from the user.

remove_service service_name Remove the specified service from the user.

set_flag flag_name Enable the specified flag on this user. Valid flags include:

• “poor_password” – User must change his/her password on the next login to the Web Interface

• “can_autodelete” – User account can be auto-deleted if the user has not logged in in a long time


PUT https://rest.luxsci.com/perl/api/v2/account/46792/users/[email protected]


{“disk_quota”: 0.75 }

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 }

10



Rename User

Change the user’s login email address from [username] to [new_address]. E.g. change

“john@sample. com” to “[email protected]”. Please note the following restrictions on this

command:

1. Users cannot be renamed with the API in the following situations:

a. Users with account administration permission cannot be renamed.

b. If this user is currently HIPAA-compliant, s/he cannot be renamed into a domain that is not

HIPAA-compliant

c. If this user does not have a SecureLine license, s/he cannot be renamed into a domain that

is HIPAA-compliant

d. Users with Spotlight Mailer user logins associated with them cannot be renamed.

e. Users cannot be renamed from a domain that does not have Premium Email Filtering or

Archival into a domain that does.

2. The new domain name (e.g. “newdomain.com”) must exist in this account.

3. The user part of the new login (e.g. “fred”) must be valid for an email address, must not

correspond to an existing user or email alias.

4. Any existing PGP or S/MIME certificates associated with this user in the system will be deleted

and become inaccessible, as they are explicitly related to the user’s login email address.

Request Method POST

Access Required Enable / Disable / Delete Users

Request URL /perl/api/v2/account/[account id]/users/[username]/rename




JSON Request Body

The Request body contains only 1 required field


new_address Email address Required. The new login username (email address) for this user.

11




POST https://rest.luxsci.com/perl/api/v2/account/46792/users/[email protected]/rename


{“new_address”: “[email protected]”}

HTTP/1.1 200 OK

Pragma: no-cache



Create User

Create a new user in your account.

Your API Interface looks to see how many users were added to your account in the past 24 hours. If

this number is equal or greater than your API create limit, then your API will reject additional user

creation requests until that situation changes. See your API Interface configuration page for your user

creation limit.

Request Method POST

Access Required Account: Add Users

and maybe also:

Account: Permit auto-upgrades as needed to fulfill requests

Request URL /perl/api/v2/account/[account id]/users




JSON Request Body

The Request body contains the following settings for the new user. If you would like to update other

user information, such as contact information, disk quota, etc., you would use other, specific API calls.

The user’s initial preferences are copied from the account main administrator user. This user will have

all licenses and services that are currently being purchased “for all users” in your account or which are

required (e.g. SecureLine for HIPAA or Archival in a domain provisioned for Archival).

12



Upgrades: If your account does not have available user licenses (or licenses for SecureLine, Archival,

or other needed services) for this new user, then either the request will be rejected, or your account

will be auto-upgraded if you have “Permit auto-upgrades as needed for fulfill requests” enabled. In the

latter case, your account will be upgraded by a block of at least your specified “licenses at a time”

upgrade setting from your API Interface configuration.


user String Required. The new username. E.g. “[email protected]”. The

domain name used must already be an active domain in your

account.

basic_spam_

filter

Integer Optional. If this is specified and its value is true (e.g. 1) AND

your account has Basic Spam Filtering licenses for all users

(which most do), then the Basic Spam Filter will be enabled

for this new user. Otherwise, the Basic Spam Filtering will not

be enabled by default.

contact String Required. The user’s full name. E.g. “John Sample”.

password String Required. The user’s password. This password must pass the

password strength requirements set for your account (unless

you send a hash).

The password sent can also be an MD5 hash (e.g. of the form

“$1$8charsalt$22-character-hash”) or an SHA512 hash (e.g.

of the form “$6$16charsalt$86-char-hash”) of the actual

password. MD5 is deprecated as it is weak; SHA512 is

recommended.

JSON Response


uid Integer The new user’s unique user ID.


POST https://rest.luxsci.com/perl/api/v2/account/73462/users


{“password”:”I L0v3 P1zza”, user: “[email protected]”, contact: “John Sample”}


13



HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: { uid: “100526”} }

Domain Management Requests

Create Domain

Create a new domain in your account. Note: the domain MUST be either a subdomain or have client-

managed DNS.

For HIPAA accounts, all new domains will be locked down for HIPAA compliance unless the account

is configured as “HIPAA Flexible.” In that case, all new domains cannot be created via the API.

Your API Interface looks to see how many domains were added to your account in the past 24 hours.

If this number is equal or greater than your API create limit, then your API will reject additional domain

creation requests until that situation changes. See your API Interface configuration page for your

domain creation limit.

Request Method POST

Access Required Account: Domain Management

Request URL /perl/api/v2/account/[account id]/domains




JSON Request Body

The Request body contains the following settings for the new domain.


accept_mail Boolean Optional: default false (“0”). True values (e.g. “1”) will result in

the domain being able to accept new email (once validated by

updating MX or A records).

14



catchall_status Enum Optional: default value “disabled”. If set to “enabled”, then the

domain-wide email catchall alias will be turned on. We do not

recommend that these be used in general ... as they are

magnets for inbound spam. If enabled, the catchall email alias

will forward all email, by default, to the main administrator of

this account (specifically, to the main admin’s username).

domain_name String Required. The name of the domain to add, e.g. “my-

domain.com”. This must be a valid domain name that does not

yet exist in your account or any other account in the system.

JSON Response


Id Integer The new domain’s unique user ID.


POST https://rest.luxsci.com/perl/api/v2/account/73462/domains


{“domain_name”: “sample-domain.com”, “accept_mail”: 1}

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: { id: “45623”} }

Delete Domain

Remove a domain from your account.

If the domain is currently in use (e.g. has users, web sites, has premium filtering or archival, has

managed DNS, etc.), then it cannot be deleted. Note: the domain MUST be either a subdomain or

have client-managed DNS.



Request URL /perl/api/v2/account/[account id]/domains/[domain_name]

15




Request Body none



DELETE https://rest.luxsci.com/perl/api/v2/account/73462/domains/sample-domain.com

HTTP/1.1 200 OK

Pragma: no-cache



Update Domain

Change selected domain settings.

Request Method PUT


Request URL /perl/api/v2/account/[account id]/domains/[domain name]




JSON Request Body

The Request body contains the following settings that can be changed for the domain. You can

change one or multiple settings via one call. Settings that are omitted will not be altered.


accept_mail Boolean Optional: False (“0”). True values (e.g. “1”) will result in the domain being able to accept new email (once validated by updating MX or A records).

Note that if “is_enabled” is false, then the domain will not accept email, even if this setting is true.

This setting will not be changed if you omit this keyword from your request.

16



catchall_action Enum Can be one of:

• “email” – to forward email messages

• “delete” – to delete email message

• “bounce” – to bounce back email messages with a custom message.

This field is required if catchall_on is true and ignored otherwise.

catchall_data String This contains data for your “catchall_action”:

• “email” – Is a comma-delimited list of email addresses to forward email to. This list will be validted.

• “bounce” – is a short plain text message (50 characters or less) to explain why the bounce is happening.

• “delete” – “catchall_data” ignored.

This field is required if catchall_on is true and catchall_action is not “delete”, and ignored otherwise.

catchall_on Boolean Optional: False (e.g. “0”). True (e.g. “1”). If enabled, then the domain-wide email catchall alias will be turned on. We do not recommend that these be used in general ... as they are magnets for inbound spam.

If enabled, then the other catchall action parameters are required.

Domain catchall settings will not be changed if you omit this keyword from your request.

is_enabled Boolean Optional: False (“0”). True values (e.g. “1”) will result in the domain globally enabled for use (e.g. email, users, etc.). This is the big “domain on/off” switch.

This setting will not be changed if you omit this keyword from your request.


PUT https://rest.luxsci.com/perl/api/v2/account/73462/domains/sample-domain.com


{“catchall_on”: 1, catchall_action: “email”, “catchall_data”: “[email protected], someone

[email protected]”, “accept_mail”: 1}

HTTP/1.1 200 OK

Pragma: no-cache



17



Get Domains Report

Get information about your domains

Request Method GET


Request URL /perl/api/v2/account/[account id]/domains


Request Body none


JSON Response Body

The data field of the response is an array of all domains in your account. Each entry in the array is an

object containing the following keyword and values:


accept_mail Boolean “1” if the domain is globally enabled and receipt of inbound

email is also enabled. Otherwise, “0”.

created DATETIME Date and time the domain was created (added to this system).

Format: “YYYY-MM-DD HH:MM:SS” in GMT

domain String Name of the domain

gid Integer Unique ID number for the account that owns this domain.

id Integer Unique domain ID number.

is_enabled Boolean “1” if the domain is globally enabled. Otherwise, “0”.

is_hipaa Boolean “1” if the domain is considered HIPAA-compliant; 0 otherwise.

is_verified Boolean

“1” if the domain’s ownership has been verified for this

account (e.g. by making the proper DNS changes). “0” if

not. Inbound

email will be rejected for domains that are not verified.

msync_users Integer Number of users in the domain with licenses for MobileSync.

secureline_

users Integer Number of users in the domain with licenses for SecureLine.

users Integer Number of users in this domain

18




GET https://rest.luxsci.com/perl/api/v2/account/73462/domains


HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, “data”: [{ “is_enabled”: 1, “is_hipaa”: 0, “msync_users”: 5, “users”: 5,

“is_verified”: 1, “created”: “2015-01-07 12:18:37”, “domain”: “my-secure-domain.com”, “accept_mail”:

1, “id”: 77351, “secureline_users”: 5, “gid”: 73462}]}

Get Domain Details

Get information about a specific domain. This is the same as the “Get Domain Report,” except that it

returns data for 1 specific domain.

Request Method GET


Request URL /perl/api/v2/account/[account id]/domains/[domain name]


Request Body none

Success Response The data will be a single object with the keys and values for the domain requested, as per the “Get Domains Report” API call, above.

Note that for this call, the data is returned without an enclosing array, as there is always exactly 1 object in the response.


GET https://rest.luxsci.com/perl/api/v2/account/73462/domains/my-secure-domain.com


HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: { “is_enabled”: 1, is_hipaa: 0, msync_users: 5, users: 5,

is_verified: 1, created: “2015-01-07 12:18:37”, domain: “my-secure-domain.com”, accept_mail: 1, id:

77351, secureline_users: 5, gid: 73462}}

19



DKIM Requests

Create DKIM

Create a new DKIM configuration in your account.

Request Method POST


Request URL /perl/api/v2/account/[account id]/dkim


Request Body none


JSON Request Body

The Request body contains the following settings for the new domain.


domain String Required. Domain name that this DKIM definition should apply

to. This is the “From” domain in email messages sent. A

DKIM definition for this domain must not already exist in the

account.

selector String Optional: default value “dkim”. Text tag to denote messages

sent using this DKIM definition (e.g., “dkim”). This must

contain only letters and numbers.

bits Integer Optional: default value 2048. Valid values: 1024, 2048, 4096.


POST https://rest.luxsci.com/perl/api/v2/account/73462/dkim


{“domain”: “sample-domain.com”}

20



HTTP/1.1 200 OK

Delete DKIM

Remove a DKIM definition from your account.



Request URL /perl/api/v2/account/[account id]/dkim/[domain_name]


Request Body none



DELETE https://rest.luxsci.com/perl/api/v2/account/73462/dkim/sample-domain.com

HTTP/1.1 200 OK

Pragma: no-cache



Get DKIM Report

Get information about your DKIM configurations

Request Method GET


Request URL /perl/api/v2/account/[account id]/dkim


Request Body none


21



JSON Response Body

The data field of the response is an array of all DKIM definitions in your account. Each entry in the

array is an object containing the following keyword and values:


domain String Domain name the definition applies to.

created DATETIME Date and time the definition was created (added to this

system). Format: “YYYY-MM-DD HH:MM:SS” in GMT

selector String DKIM selector

dns String

Main DNS text record to add to implement the DKIM. Other

required DNS TXT records do not depend on configured DKIM

details.

Get DKIM Details

Get information about a specific DKIM configuration. This is the same as the “Get DKIM Report,”

except that it returns data for 1 specific domain.

Request Method GET


Request URL /perl/api/v2/account/[account id]/dkim/[domain name]


Request Body none

Success Response The data will be a single object with the keys and values for the domain requested, as per the “Get DKIM Report” API call, above.

Note that for this call, the data is returned without an enclosing array, as there is always exactly 1 object in the response.


GET https://rest.luxsci.com/perl/api/v2/account/73462/dkim/my-secure-domain.com


22



Email Suppression

Create Suppression

Add new email suppressions at the account level.

Request Method PUT

Access Required User Email: Suppression

Request URL /perl/api/v2/account/[account id]/suppression



Success Response No body returned.

JSON Request Body


emails String Required. A comma-delimitd list of email addresses to

suppress. You can include between 1 and 1000 addresses

in this parameter.

Expires Integer Optional. A positive integer. If included, the suppressions

created will expire after this many days. If omitted, the

suppressions will not expire.


PUT https://rest.luxsci.com/perl/api/v2/account/73462/suppression


{“emails": "[email protected],[email protected]", expires: 30}

HTTP/1.1 200 OK

Pragma: no-cache



23



Delete Suppression

Delete a specific account-level email suppression.



Request URL /perl/api/v2/account/[account id]/suppression/email


Request Body none

Success Response No body returned.


DELETE https://rest.luxsci.com/perl/api/v2/account/73462/suppression/[email protected]

HTTP/1.1 200 OK

Pragma: no-cache



Get Suppression

Retrieve a specific email suppression at the account level.



Request URL /perl/api/v2/account/[account id]/suppression[/email]


Request Body none

Success Response The [/email] part of the URL is optional. With it, you are returning all suppression entries that contain the string "email". Without it, you return all suppression entries altogether. Note that even if you specify a full email address for "email," you can get multiple results.

24



The data will be a single object that is a list containing one entry for each match. Each entry will itself be a list of the form

[ email, expires, account_id, domain_id, user_id ]

• "email" is the email address suppressed

• "expires" is the number of days until it expires, or zero if it doesn' expire.

• account_id is the customer account id

• domain_id is zero for account-level entries, or the domain name id for domain and user-level entries

• user_id is zero except for user-level suppression entries, in which case it is the end user id number.


GET https://rest.luxsci.com/perl/api/v2/account/73462/suppression/[email protected]

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: [[ "[email protected]", 0, 100001, 0, 0]] }

Email Alias Management Requests

Create Alias

Create new alias(es) in your account.

Your API Interface looks to see how many aliases were added to your account in the past 24 hours. If

this number is equal or greater than your API create limit, then your API will reject additional alias

creation requests until that situation changes. See your API Interface configuration page for your alias

creation limit.

25



Note also that accounts are limited in the maximum number of email aliases permitted per domain. By

default, this is 100 + 10 aliases per user in the domain. So, for a domain with 20 users, this would be

100 + 10x20 = 300 aliases.

Request Method POST

Access Required Account: Alias Management

Request URL /perl/api/v2/account/[account id]/aliases




JSON Request Body

The Request body contains the following settings for new email aliases. While you can add multiple

aliases at once, you should not have duplicates in your list.


aliases Array Array of objects for aliases to create. Each object can have

the following keywords:

• “user” – Required. The user part of the alias address.

E.g. “john” in “[email protected]”. This must be a valid

user part of an email address and less than 65

characters ling.

• “domain” – Required. The domain part of the alias

addres. E.g. “sample.com”. This must be an active

domain in this account.

• “action” – Required. One of “email”, “bounce”, or “delete”

to define what happens to messages to this alias:

forward them via email, bounce them with a message, or

delete them.

• “dest” – The “destination” for actions of type “email”. This

is a comma-delimited list of email addresses to whom to

forward the message.

• “bounce” – The short 50-character or less ANSI-

encoded failure message to send back when the action

is “bounce”

26



JSON Response


added Integer Number of new aliases that were created (e.g. for validation

purposes).


POST https://rest.luxsci.com/perl/api/v2/account/73462/aliases


{“aliases”: [{“user”:”john”, “domain”:“sample.com”, “action”: “bounce”, “bounce”: “Address no longer

valid.” }]}

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: { added: 1} }

Update Alias

Modify an existing alias in your account.

This function allows you to modify regular email aliases in your account. It does not permit

modification of “catch all” aliases, “user forwards,” and system aliases such as WebAide Group

Distribution Lists. You can use this function to enable and disable aliases; however, you must use a

separate API call to actually delete them.

Request Method PUT


Request URL /perl/api/v2/account/[account id]/aliases/[alias address]

Request Query String None


Success Response None

JSON Request Body

The Request body contains the following settings for updating an email alias.

27




action Enum Required. One of “email”, “bounce”, or “delete” to define what

happens to messages to this alias: forward them via email,

bounce them with a message, or delete them.

bounce String The short 50-character or less ANSI-encoded failure message

to send back when the action is “bounce”. Required for aliases

of action “bounce”.

dest Email List The “destination” for actions of type “email”. This is a comma-

delimited list of email addresses to whom to forward the

message. Required for aliases of action “email”.

status Enum Required. Must be “enabled” or “disabled”. This sets the status

of the email alias.


PUT https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]


{ “action”: “email”, “dest”: “[email protected], [email protected]”, “status”: “enabled”}

HTTP/1.1 200 OK

Pragma: no-cache



Delete Alias

Remove an alias with the specified alias email address from your account.





Request Body none

28





DELETE https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]

HTTP/1.1 200 OK

Pragma: no-cache



Get Aliases Report

Get information about your email aliases including regular aliases, user forwards, domain catchalls,

and WebAide Group distribution lists.

Request Method GET


Request URL /perl/api/v2/account/[account id]/aliases


Request Body none


JSON Response Body

The data field of the response is an array of all aliases in your account. Each entry in the array is an

object containing the following keyword and values:


action Enum What to do with email to this alias. This must be one of “email”, “bounce”, or “delete”.

bounce String For aliases whose action is “bounce”, this is the bounce message.

created DATETIME When the email alias was created. Format: “YYYY-MM-DD HH:MM:SS” in GMT. Some types of aliases may not have a creation time recorded (as may aliases created before

29



creation times started to be tracked). These will return a created value of “0000-00-00 00:00:00”.

dest Email List For aliases whose action is “email”, this is the comma-delimited list of destination email addresses

distribution_

list_group

String For aliases whose type is “distribution”, this is the name of the WebAide Group.

domain String Domain name (e.g. for alias “[email protected]”, this would be “sample.com”)

msync_users Integer Number of users in the domain with licenses for MobileSync.

secureline_

users Integer Number of users in the domain with licenses for SecureLine.

status Enum This will be “enabled” for aliases that are “on” and “disabled” for ones that exist but which are “off”.

Type Enum The source or kind of alias. This would be one of:

• Catchall – domain catchall

• Forward – a user’s email forwarding rule

• Alias – a regular email alias

• distribution – A WebAide Group distribution list

user String User part of alias address (e.g. for alias “john@sample. com”, this would be “john”). For catchall aliases, this is empty or null.

users Integer Number of users in this domain


GET https://rest.luxsci.com/perl/api/v2/account/73462/aliases


HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: [{bounce: null, dest: ‘[email protected]’, status: ‘enabled’,

domain: ‘sample.com’, user:’john’, action:’email’, type:’Alias’, distribution_list_group: null,

created:’2015-03-02 07:11:33’}]}

Get Alias Details

Get information about a specific email alias.

Request Method GET


30






Request Body none


JSON Response Body

The data field of the response is an on object whose keywords and values correspond to those in the

“Get Aliases Report”. This is the same as that function, except that it is targeted at a specific alias and

thus instead of returning a list of alias detail objects, it simply returns the single alias detail object.


GET https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]


HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: {bounce: null, dest: ‘[email protected]’, status: ‘enabled’,

domain: ‘sample.com’, user:’john’, action:’email’, type:’Alias’, distribution_list_group: null,

created:’2015-03-02 07:11:33’}}

SecureForm Management

Customers with SecureForm services can use these functions to manage their forms and to access

form data posted and saved in a database by the SecureForm system.

Get SecureForm List

Return a list of all SecureForm configurations currently defined in your account.

Request Method GET

Access Required Account: SecureForm Configuration

31



Request URL /perl/api/v2/account/[account id]/secureforms


Request Body none

Success Response see below

JSON Response Body

The Response Body contains a “data” keyword which is an array of objects, one for each SecureForm

configuration. They keywords in these objects and their meanings are:


action Set What will be done with posted data? This is a comma- delimited list of actions:

• archive – Save to a WebAide

• email_data – Send via email

• email_notice – Send a notification email

• ftp – Save to an FTP or SFTP site

• mysql – Save to a hosted database

• schat – Send to SecureChat

archive_content Set What will be saved to a WebAide? This is a comma-delimited list of data types (posted files are always saved):

• 2col – Two-column HTML view of keywords and values

• csv – CSV file

• html – Custom re-filled HTML template

• pdf – Custom re-filled PDF template

• text – Plain text view of keywords and values

• xfdf – Posted FDF file from a PDF form

• xml – XML version of keyword and value data

• xpdf – Posted full PDF from a PDF form

db_host Text For configurations saving to a database, this is the hostname of the database

db_name Text For configurations saving to a database, this is the name of the database

db_table Text For configurations saving to a database, this is the base table name for the table(s) that will conatin the post data

email_content Set What will be sent via email? This is a comma-delimited list of data types (posted files are always sent):





32







ftp_content Set What will be uploaded to FTP/SFTP? This is a comma- delimited list of data types (posted files are always uploaded):









id Integer SecureForm configuration unique ID. This is used in API function calls that operate on a specific SecureForm configuration.

last_post DATETIME Date and time of the last post to this SecureForm configuration. Same format as “modified”. This will be undefined if there has not yet been any posts to this SecureForm configuration.

modified DATETIME Date and time this configuration was last modified in GMT.

Format (YYYY-MM-DD HH:MM:SS)

mysql_encrypt Integer • 0 – Data saved to a database will not be encrypted at rest

• 1 – Data saved to a database will be encrypted at rest

notes Text Your internal plain text notes for this SecureForm configuration.

secure Integer • 0 – Configuration does not have “secure” connections and options required.

• 1 – Configuration has “secure” connections and options required.

status Integer • 0 – Configuration disabled

• 1 – Configuration active

title Text Title of this SecureForm configuration

type Enum Source of the form data is:

• web – A web site form

• pdf – A PDF form

33




GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 , data: [{ ‘archive_content’: ‘csv’, ‘status’: 1, ‘secure’: 1, ‘ftp_content’: null,

‘modified’: ‘2015-02-07 16:25:44’, ‘mysql_encrypt’: 1, ‘last_post’: ‘2015-05-01 11:33:17’, ‘notes’: null,

‘email_content’: ‘text,pdf’, ‘action’: ‘email_data,mysql’, ‘type’: ‘pdf’, ‘title’: ‘My Example Form’, ‘id’:

2567981, db_host: ‘mysql55.web10.luxsci.com’, db_name: ‘dr_office_db’, db_table: “intake_forms” }]}

Get SecureForm

Returns details on a specific SecureForm configuration, based on the configuration’s unique ID.

Request Method GET


Request URL /perl/api/v2/account/[account id]/secureforms/ID


Request Body none


JSON Response Body

The Response Body contains a “data” keyword contains one object which provides details about the

specified form. The keywords and values in this object are the same as those defined for the “Get

SecureForm List” operation.


GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895

HTTP/1.1 200 OK

Pragma: no-cache


34



{“auth”: [omitted],”success”:1 , data: { ‘archive_content’: ‘csv’, ‘status’: 1, ‘secure’: 1, ‘ftp_content’: null,

‘modified’: ‘2015-02-07 16:25:44’, ‘mysql_encrypt’: 1, ‘last_post’: ‘2015-05-01 11:33:17’, ‘notes’: null,

‘email_content’: ‘text,pdf’, ‘action’: ‘email_data,mysql’, ‘type’: ‘pdf’, ‘title’: ‘My Example Form’, ‘id’:

2567981, db_host: ‘mysql55.web10.luxsci.com’, db_name: ‘dr_office_db’, db_table: “intake_forms” }}

Get SecureForm Database Info

Returns details on the posts currently stored in the database table associated with a specific

SecureForm configuration. This function is recommended for use when synchronizing or periodically

downloading new rows to an external source: it allows you to quickly and easily see what, if any,

entries are new relative to your last actions (if you saved the last index or date when you previously

downloaded data).

Request Method GET


Account: SecureForm Database Read

Request URL /perl/api/v2/account/[account id]/secureforms/ID/db

Request Query String see below

Request Body none



You can optionally pass one or more parameters to narrow down the scope of what rows are

examined to produce the summary results. By default, all table rows are examined. All criteria passed

as parameters are used; it is possible (and easy) to specify mutually exclusive parameters that result

in no rows being examined (e.g. all rows with an index greater than 100 and less than 50).


after_date DATETIME All rows added after the specified date time (in GMT,

format “YYYY-MM-DD HH:MM:SS”).

after_index Integer All rows whose index is greater than the specified value.

before_date DATETIME All rows added before the specified date time

before_index Integer All rows whose index is less than the specified value.

from_date DATETIME All rows added on or after the specified date time

35



from_index Integer All rows whose index is greater than or equal to the

specified value.

through_date DATETIME All rows added on or before the specified date time

through_index Integer All rows whose index is less than or equal to the specified

value.

JSON Response Body

The Response Body contains a “data” object with keywords and values. These are:


oldest_post DATETIME Date when the oldest matching row was added (in GMT,

format “YYYY-MM-DD HH:MM:SS”).

newest_post DATETIME Date when the newest matching row was added.

number_of_entries Integer Number of matching rows.

max_index Integer Index of the newest matching row.


GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db?after_index=10

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 , data: {“number_of_entries”:3,”oldest_post”:”2014-03-26

20:41:56”,”newest_post”:”2014-03-26 20:45:13”,”max_index”:13}}

Get SecureForm Database Rows

This function returns the actual content of all database rows matching your query. Encrypted database

fields will be automatically decrypted and the actual values of the fields returned.

This API call is audited: a record will be made of the particular API Integration and IP address that

“read” each matching row.

Request Method GET

36





Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/rows

Request Query String see below

Request Body none



You can optionally pass one or more parameters to narrow down the scope of what rows are returned.

These parameters are the same as those for “Get SecureForm Database Info”.

JSON Response Body

Up to 500 rows can be returned per API call. If more rows match, only the first 500 (sorted by row

index) are actually returned. The “data” body element will contain 2 items.

The first is called “fields”. This is an object where the keywords are the physical database column

names in use for each column of data. These keywords correspond to the keywords in the objects

returned in the “rows” array. The values of these keywords are corresponding the actual field names

from your form. E.g. in many cases the form field name cannot be used “as is” as a database column

name and must be “sanitized”. You can use this “fields” object to map between the database column

names and the original form field names.

The second is called “rows”. This is an array of objects. Each object contains the data for a single

matching row. The keywords are the database column names, the values are the row values for those

columns. Values that were encrypted in the database are automatically decrypted and the real value is

returned. If the row cannot be decrypted using the saved encryption key for this SecureForm

configuration (e.g. if it was saved using some other SecureForm configuration and a different key),

then the encrypted row values will all have the value of the word “ENCRYPTED”.

Files are not downloaded with this function; however, information as to what files are available is

included with each row of data.

Separate functions are used to request individual files.

Explanations of common database columns

Column Data Type Description

__encrypt__ Integer Value of 1 if the row is encrypted at rest in the database; 0

if not.

37



__files__ Array An array of file information that can be used to manipulate

the files associated with this post/row. Each item in this

array is an object representing one of the associated files.

The keywords in these objects are:

• file_id – Unique (integer) ID for this file

• size – Size in bytes of this file

• name – Filename for this file

__index__ Integer Unique index for this form post / database row.

__ip_address__ String IP Address of the computer used by the end user who

submitted this form post.

__n_files__ Integer The number of files associated with this post/row that are

currently saved in the database.

__posted__ DATETIME Date and time the data was saved to this database table in

GMT (format “YYYY-MM-DD HH:MM:SS”)

__referrer__ String HTTP Referer passed by the end user’s web client.


GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/rows?after_index=12

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 , data: { fields: {“__ip_address__”:”__ip_address__”,

“__index__”:”__index__”,”__referrer__”:”__referrer__”, “__posted__”:”__posted__”,

”example_field_name”:”Example Field Name”}}, rows: [ { ‘__index__’: 13, ‘__referrer__’: null,

‘__posted__’: ‘2015-05-15 11:15:03’, ‘__n_files__’: 1, ‘__files_’: [ {‘file_id’: 179, ‘size’: 67996, ‘name’:

‘test_file.txt’} ], ‘__encrypt__’: 1, __ip_address__: ‘4.2.2.1’, ‘example_field_name’:

‘example_field_value’ }, { ‘__index__’: 14, ‘__referrer__’: null, ‘__posted__’: ‘2015-05-16 12:02:43’,

‘__n_files__’: 0, ‘__files_’: [], ‘__encrypt__’: 1, __ip_address__: ’65,43,123,41’, ‘example_field_name’:

‘another example value’ } ] }}

Get SecureForm Database Row

This function works the same as “Get SecureForm Database Rows”, except that you specify the row

index and get back up to 1 row. This index is the __index__ field for the row.

38




“read” each matching row.

Request Method GET



Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/INDEX


Request Body none


JSON Response Body

The JSON response body is the SAME as that returned for the “Database Rows” command, except

that insted of a “rows” keyword with an array of matching rows, there is a “row” keyword which holds

the object data for the requested row. This will be “null” if that row was not found.


GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 , data: { fields: {“__ip_address__”:”__ip_address__”,

“__index__”:”__index__”,”__referrer__”:”__referrer__”, “__posted__”:”__posted__”,

”example_field_name”:”Example Field Name”} }, row: { ‘__index__’: 13, ‘__referrer__’: null,

‘__posted__’: ‘2015-05-15 11:15:03’, ‘__n_files__’: 1, ‘__files_’: [ {‘file_id’: 179, ‘size’: 67996, ‘name’:

‘test_file.txt’} ], ‘__encrypt__’: 1, __ip_address__: ‘4.2.2.1’, ‘example_field_name’:

‘example_field_value’ }, }}

Delete SecureForm Database Row

This function allows you to delete a row from your SecureForm database, based on the row index.

This function will delete the row and any associated files.


“deleted” each matching row (also implying that any associated files have been removed).

39



Request Method Delete

Access Required

Account: SecureForm Configuration


Account: SecureForm Database Delete

Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/INDEX


Request Body none

Success Response standard simple response


DELETE https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13

HTTP/1.1 200 OK

Pragma: no-cache



Get SecureForm Database File

This function is used to retrieve a file associated with a row in your SecureForm database. You will

need the row index and the file ID (which you can retrieve by reading the row data using other API

calls).

If the file was encrypted at rest in the database, it will be decrypted for you.


“read” each file.

Request Method GET



Request URL /perl/api/v2/account/[account

id]/secureforms/ID/db/ROW_INDEX/file/FILE_INDEX


Request Body none


40



JSON Response Body

The JSON response body has a data object with the following keywords and values:

__encrypt__ 1 if the file was encrypted at rest, 0 otherwise.

file_base64 BASE64-encoded file data. If you decode this, you will have the raw

file content.

name The file’s name.

size Size in bytes of the raw file (un-encoded).

uploaded DATETIME (in GMT, the usual format) when the file was uploaded/

saved to the database


GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13/file/179

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1 , data: {“uploaded”:”2015-05-12

11:49:36”,”__encrypt__”:1,”name”:”test.html”, “file_ base64”:”PGI+dGVzdCBodG1sPC9iPg==”,

“size”:17}}

Delete SecureForm Database File

This function is used to remove a file associated with a row in your SecureForm database. You will

need the row index and the file ID (which you can retrieve by reading the row data using other API

calls).


deleted each file.




Account: SecureForm Database Delete

Request URL /perl/api/v2/account/[account

id]/secureforms/ID/db/ROW_INDEX/file/FILE_INDEX

41




Request Body none

Success Response standard


DELETE https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13/file/179

HTTP/1.1 200 OK

Pragma: no-cache



SecureSend NameSpace Management

Customers with Private Labeling and SecureLine may choose to setup NameSpace(s) to associate

with their Private Labeled themes. These NameSpaces segregate the SecureSend users of these

themes from the SecureSend users of other themes and of other LuxSci customers. These functions

allow you to manage the users in a particular SecureSend NameSpace in your account.

You need your “namespace id” number to use these functions. This can be found in the “SecureSend

User NameSpaces” page accessible in your Private Labeling configuration area. These API functions

only permit you to manage users in NameSpaces in your account.

Create/Update SecureSend User

Create a new SecureSend User in a specific NameSpace. This function also validates the user’s

account so the user does not have to do anything (like checking a link in his/her email) to start using

the account.

If an account already exists for the specified user, then this request will merely update the user’s

account, changing any data passed through. The “username” must be the email address (which is

also the login) of the user to be created or updated.

When updating a user, request parameters omitted will not be updated.

Request Method PUT

42



Access Required SecureSend NameSpace Management

Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace

id]/users/[username]



Success Response Standard simple success

JSON Request Body

The Request body contains the following settings.


name String Real name of the user. E.g. “John Sample”. This is

required for user creation and optional for user update.

password String Password for this user to the SecureSend Portal. ”. This is

required for user creation and optional for user update. We

place the burden of choosing a strong password on your

API client. We only restrict the password minimally –

requiring it be 6+ characters long and contain letters [a-zA-

Z] and non-letters.

timezone String Valid time zone code. E.g. “EST5EDT”. Optional. If omitted

on user creation, a time zone of “GMT” will be used


PUT https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/[email protected]


{ “name”: “John Sample”, “timezone”: “EST5EDT”, “password”: “slkjf656g!” }

HTTP/1.1 200 OK

Pragma: no-cache



43



Change SecureSend User Password

You can do this with the User Update function, above. We provide a simple, direct method here as

well.

Request Method PUT



id]/users/[username]/password



Success Response Standard simple success

JSON Request Body

The Request body contains the following settings.


password String Required. Password for this user to the SecureSend Portal. ”.

We place the burden of choosing a strong password on your

API client. We only restrict the password minimally – requiring it

be 6+ characters long and contain letters [a-zA-Z] and non-

letters.


PUT https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/john@sample.

com/password


{ “password”: “slkjf656g!” }

HTTP/1.1 200 OK

Pragma: no-cache



44



Get SecureSend User Single Sign-On Link

Create a URL that the user can click on which will automatically log the user into the SecureSend

Interface without needing to enter his/her username and password. For example, if the user has

already authenticated him/herself in your system, you can use this API call to get a link that can be

presented to the user so the user can then access SecureSend without needing to login again (e.g.

“single sign-on”).

Notes:

1. This API call returns a URL. You can have the user click on that URL or you can redirect

him/her to it.

2. This URL is valid for 15 minutes from the time of issuance. It can be used multiple times while

it is in use.

3. These URLs are invalidated if the user’s password is changed.

4. These URLs will only work for someone coming from the IP address that your specified in your

request for the URL

5. All logins via Single Sign-on are logged in the user’s History and are denoted as Single Sign-on

logins therein

Request Method GET


SecureSend Single sign-On


id]/users/[username]/password

Request Query String See below

Request Body none


Query String


ip IPv4 The public IP address that the user is currently using. The

resulting URL will only work for people accessing it from this IP.

theme Integer The numerical Private Labeled Theme ID that this link should be

generated for. You can find these IDs in your theme management

area.

45



Not that the SecureSend NameSpace specified must be

associated with this Theme, or the API will return an error.

Result

This returns the URL.


url String URL for the end user to go to so that s/he can login to SecureSend without a username or password.


GET https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/john@sample.

com/password


{ ip: “5.33.44.1”, theme: 1788906572 }

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: { url: “https://rest.luxsci.com/perl/public/securesend

pl/37/6451?login-single-signon=1-6451-1429730454-433647730c8572bd1b6e17b01c19b1174

deb88823d56f737f3aba7b491cf5be&settheme=1788906572”} }

Get SecureSend User List

Return a list of all users in this NameSpace.

Request Method GET


Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace id]/users


Request Body none


46



Result

This returns a list of objects. The objects will have keys with values as described, below:


created DATETIME When the user was created, in GMT. Format “YYYY-MM-DD

HH:MM:SS”

email String Email address and login username for the user

lastlogin DATETIME When the user last logged into SecureSend (in any way). In

GMT.. Format “YYYY-MM-DD HH:MM:SS”. If the user has

never logged in, this will have the value “0000-00-00

00:00:00”.

name String User’s name.

status Enum • verified: user can login

• pending: user has registered but not verified his/her

identity/email

• suspended: user account suspended

timezone String Time zone code for this user


GET https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users


{ ip: “5.33.44.1”, theme: 1788906572 }

HTTP/1.1 200 OK

Pragma: no-cache


{“auth”: [omitted],”success”:1, data: [{ email: “[email protected]”, name: “John Sample”, timezone:

“GMT”, status: “verified”, created: “2015-04-22 15:34:01”, lastlogin: “2015-04-22 15:02:45” } ] }

Reports

There are many reports available in the LuxSci user interface. Some of these are account-wide and

some are the same reports, but restricted to a particular user’s activity. Some of these reports are

exposed via this API for automated access.

47



Access to all of these reports is very similar. They all use an HTTP GET; account-wide reports use

account scope; user-specific reports are available under user scope; all reports use the same

mechanism for restricting date ranges and requesting particular “pages” of results. The following

section specifies the usage features common to all of these report types. The subsequent sections

discuss each of the particular account scope reports available. See the “User” guide for a list of the

respective user scope reports.

Report Querying and Results: Commonalities

All API queries for “Reports” are HTTP GETs with optional query strings that allow you to narrow down

the scope of the request and/or select which of the many matches to actually return. The following

table lists the optional query string parameters that you can use with any report request. The meaning

of “date” referred to in the date restrictions will depend on what API call is being executed.


after_date DATETIME Return only matches dated after this date time. Format

“YYYY-MM-DD HH:MM:SS” in GMT.

before_date DATETIME Return only matches dated before this date time.

first_row Integer (Default value 0). All of the matches are sorted and numbered

starting from 0. E.g. if you have 100,000 matches, these are

rows 0 through 99,999. If you specify a first_row, then the

returned matches will be those rows starting from that row.

E.g. without a specification (or if you specify 0), you might get

rows 0 through 49,999. In your next request you might specify

first_row=50000 to get rows 50000 to 99,999.

from_date DATETIME Return only matches dated on or after this date time.

matches Integer (Default value 50000). You can set matches to any value from 0

to 50000. This sets the maximum number of matches that will

be returned in response to your request. Note that if the

response size starts to exceed 50MB, then the response can

still include fewer than your “matches” number, to keep the

response size reasonable. If you specify “0” here, then no

matches will be returned; however, you will still get the

information on the number of matches that there were.

through_date DATETIME Return only matches dated before or on this date time.

48



Additional query string parameters, specific to specific reports, are described in those sections.

The response to a successful Report request will be a JSON object with a data section that is an

associated array formatted with a standard set of keywords:


First Integer The index of the first row that was returned. E.g. this should

match the “first_row” parameter specified in the request.

header ARRAY Array that includes the column headings for all of the matches

returned.

matches_returned Integer The number of matching rows returned in the “rows” array.

matches_total Integer The number of rows matching your request. Note that this can

be larger than the number of rows returned.

rows ARRAY Array of data for all matches returned. This array contains one

element for each returned match. Each element is itself an

array. Each field in the match arrays corresponds to the

respective field in the “header” array. E.g. if the 1st element in

the “header” array is “user_id”, then the 1st element in a

match data array will be the integer user ID number, etc.

Note: A report query could match zero to millions of rows, depending on the report and the context.

Returning millions of rows in response to a single request is not feasible as the download would be

absolutely huge. Report result sets are limited to at most 50,000 matches or about 50MB of data

(whichever occurs first). If your query matches more than that, then only a subset of matches is

returned. We recommend using the query parameters and the result data to page through your results

as needed. We also recommend using the data restriction options to make your requests as specific

as possible – this will make them faster and allow them to return smaller result sets.

Report: Email Sent

Return a list of all email messages sent by users in this account.

Request Method GET

Access Required Account: View Reports

Request URL Messages sent via SMTP or ActiveSync from email programs and

devices:

/perl/api/v2/account/[account id]/report/email/smtp/sent

49



Messages sent via WebMail

/perl/api/v2/account/[account id]/report/email/webmail/sent

Request Query String All standard reporting parameters, plus See Below.

Dates, for the purposes of narrowing results, refer to the date the

message was sent (as defined as the date/time it was received by the

API). This corresponds to the “date_sent” output field.

Request Body none

Success Response Standard response for all reports. Data field details listed below.

Additional Query String Parameters


from String Case-insensitive substring search of the message “From” email address

header1 String Case-insensitive name of the custom email header field to match against in the “header 1” column. I.e., if you were matching against “X-My-Header” and saving this in header 1, you would enter “X-My-Header” as the value here.

NOTE: Data is only stored in the customer header capturing fields/columns if you have explicitly enabled this feature in the “Account Administration > Email” area of the LuxSci user interface.

header1_operator Enum If this is present and one of the following 4 values, then the query will only return messages that included “header1” when “header1” was being tracked, and which also satisfy the follow the criteria:

• is --- The value of the email header named “header1” in the send email must have been exactly the same as header1_value

• not – The value of the email header named “header1” in the send email must not be exactly the same as header1_value

• like – The value of the email header named “header1” in the send email must contain (case insensitive) the value in header1_value

50



• notlike – The value of the email header named “header1” in the send email must not contain (case insensitive) the value in header1_value

I.e., if you configured your account to capture the value of the header “X-My-Header” and saving this in “header column 1” and an email was sent with the header “X-My-Header: gh6577hh-abc”. This would have been stored in the database. You could then find this message by passing to this API function:

• header1 = “X-My-Header”

• header1_operator = “is”

• header1_value = “gh6577hh-abc”

Or by passing:

• header1 = “X-My-Header”

• header1_operator = “like”

• header1_value = “abc”

header1_value String Text used with “header1_operator” for matching the value of the email header specified in the “header1” parameter in the original sent message.

header2 String Like “header1” but applies to searching the header 2 column.

header2_operator Boolean Like “header1_operator” but applies to searching the header 2 column.

header2_value String Like “header1_value” but applies to searching the header 2 column.

header3 String Like “header1” but applies to searching the header 2 column.

header3_operator Boolean Like “header1_operator” but applies to searching the header 2 column.

header3_value String Like “header1_value” but applies to searching the header 2 column.

ip String Case-insensitive substring search of the sender IP address (for SMTP reports only).

51



opt_out Enum Value:

0 – SecureLine Opt Out not used

-1 – SecureLine Opt Out use not recorded for some reason

1 – SecureLine Opt Out

secureline Enum Value:

any – Match anything

-1 – SecureLine usage not recorded for some reason

1 – SecureLine encryption was used

0 – SecureLine encryption was not used

If SecureLine was used, use the delivery status report to see more details.

sendmail_id String Return only the message with the specified sendmail_id.

sendmail_ids String Comma-delimited list of up to 100 sendmail ids. Returns any matching messages.

spam Enum Value:

0 – Message was not marked as spam by a recipient and returned in a Feed Back Loop

1 – Message was marked as spam by a recipient and returned in a Feed Back Loop

subject String Case-insensitive substring search of the message subject (in

UTF-8).

to String Case-insensitive substring search of all recipient email

addresses.

tracked_headers Boolean If true and this report is for messages sent vis SMTP, then the results will include the six additional fields (header1, header2, header3, header1_value, header2_value, header3_value) which are used to track custom email message header data.

user_id Integer Restrict the report to the user with this specific User ID

number.

JSON Response Body

The header columns in the response include the following:


date_sent DATETIME When the message was sent In GMT. Format “YYYY-MM-DD

HH:MM:SS”.

52



from String From email address

from_ip String IP Address of the sending program (SMTP reports only). This

can be just “MobileSync” if this was sent via MobileSync /

Exchange ActiveSync.

header1 String Present only if “tracked_headers” was passed as a

parameter. This is the name of the email header captured

in header column 1 for this message (all lower case). As

your capturing settings can be changed and different

messages may have differing headers, different messages

could have captured different headers (or none at all) in

“column 1”.

header1_value String Present only if “tracked_headers” was passed as a

parameter. If a custom header was captured in “column 1”

(as indicated by the “header1” field), this is the value of that

email header.

I.e., if you configured your account to capture the value of the

header “X-My-Header” and saving this in “header column 1”

and an email was sent with the header “X-My-Header:

Gh6577hh-abc”, then the value of “header1” would be “x-my-

header” and the value of “header1_value” would be

“Gh6577hh-abc”.

header2 String Same as “header1” but for header column 2.

header2_value String Same as “header1_value” but for header column 2.

header3 String Same as “header1” but for header column 3.

header3_value String Same as “header1_value” but for header column 3.

53



high_volume Integer Value:

0 – Message sent does not count towards a High Volume or

Premium High Volume sending limit

1 – It does.

n_recipients Integer Number of recipients to the message

notes String Internal notes

opt_out Integer Value:

0 – SecureLine Opt Out not used

-1 – SecureLine Opt Out use not recorded for some reason 1

– SecureLine Opt Out

secureline Integer Value:


1 – SecureLine encryption was used

0 – SecureLine encryption was not used

sendmail_id String Unique sendmail_id of this message; useful for tracking

purposes.

size_bytes Integer Size of the message in bytes.

spam Integer Value:

0 – Message was not marked as spam by a recipient and

returned in a Feed Back Loop

1 – Message was marked as spam by a recipient and returned

in a Feed Back Loop

to String Comma-delimited list of recipient email address(es).

used_tls Integer Value: (SMTP Only)

1 – TLS was used in the connection from the sending program

to the server.

0 – TLS was not used in this connection.

user String Login mail address of the user who sent the message

user_id Integer User ID of the user who sent the message

Report: Email Delivery Status

This report allows you to see how each message was sent to each recipient and what the delivery

status is for each of these recipients. Note that delivery status changes over time as messages

54



progress to the recipient’s servers and as bounce messages are sent back and processed. As the

delivery status changes, the “last_update” date is also updated.

Request Method GET



devices:

/perl/api/v2/account/[account id]/report/email/smtp/delivery


/perl/api/v2/account/[account id]/report/email/webmail/delivery



message delivery status was last updated. This corresponds to the

“last_update” output field.

Request Body none



Keyword Data

Type

Description

clicked Integer If specified, the results are restricted as follows:

clicked < 0 – select messages where URL click tracking was not

enabled.

clicked = 0 – select messages where URL click tracking was

enabled, but where there have as yet been no clicks on any

clinks in the messages.

clicked > 0 – select messages where URL click tracking was

enabled and where there have been N or more clicks on links in

the same message to the same recipient. N, in this case, is the

number that you have specified as the value of the “clicked”

parameter. I.e., using a value of “1” matches all messages that

have had a link clicked on.

from String Case-insensitive substring search of the message “From” email

Address

55



ip String Case-insensitive substring search of the sender IP address (for

SMTP reports only).

header1 String See: “Report: Email Sent”

header1_operator Enum See: “Report: Email Sent”

header1_value String See: “Report: Email Sent”







opened Integer If specified, the results are restricted as follows:

opened < 0 – select messages where open tracking was not

enabled.

opened = 0 – select messages where open tracking was

enabled, but which have not yet been opened.

opened > 0 – select messages where open tracking was

enabled and which have been opened at least N times. N, in

this case, is the number that you have specified as the value of

the “opened” parameter. I.e., using a value of “1” matches all

messages that have been opened.

secureline Enum Value:

u – Message to this recipient did not use SecureLine (or Opt Out

was used)

e – Message did use SecureLine

-2 – SecureLine was not used due to Opt Out being selected


1 – SecureLine:PGP was used

2 – SecureLine:S/MIME was used

3 – SecureLine:Escrow was used

4 – SecureLine:TLS was used

sendmail_id String Return only the messages with the specified sendmail_id.

sendmail_ids String Comma-delimited list of up to 100 sendmail ids. Returns any

matching messages.

56



spam Enum Value:

0 – Message was not marked as spam by a recipient and

returned in a Feed Back Loop

1 – Message was marked as spam by a recipient and returned in

a Feed Back Loop

tls Enum Value:

0 – TLS was NOT used in the successful delivery of this message

to the recipient server

1 – TLS was used in the successful delivery of this message to

the recipient server

tracked_headers Boolean See: “Report: Email Sent”

To String Case-insensitive substring search of all recipient email

addresses.

user_id Integer Restrict the report to the user with this specific User ID number.

JSON Response Body

The header columns in the response include the following (see below). Additionally, the 6

headerN/headerN_value columns are also returned if the “tracked_headers” parameter is sent with a

true value (see “Report: Email Sent”).


date_sent DATETIME When the message was sent (in GMT). Format “YYYY-MM-DD

HH:MM:SS”.


from_ip String IP Address of the sending program (SMTP reports only). This can

be just “MobileSync” if this was sent via MobileSync / Exchange

ActiveSync.







57



last_updated DATETIME When this delivery status information was last updated. E.g. for

messages in the queue, they can be retried many times and each

retry can result in an update to the queue reason (state_detail) or

delivery status. Message status can also be update much later

after sending as hard bounces come back.

n_recipients Integer Number of recipients to the message

secureline Integer Value:

0 – Message to this recipient did not use SecureLine

-2 – SecureLine was not used due to Opt Out being selected


1 – SecureLine:PGP was used

2 – SecureLine:S/MIME was used

3 – SecureLine:Escrow was used

4 – SecureLine:TLS was used

sendmail_id String Unique sendmail_id of this message; useful for tracking purposes.

size_bytes Integer Size of the message in bytes.

spam Integer Value:

0 – Message was not marked as spam by a recipient and returned

in a Feed Back Loop

1 – Message was marked as spam by a recipient and returned in

a Feed Back Loop

status Enum Delivery status of the message to this recipient. Values:

Delivered – Successfully delivered

Failed – Permanently failed to be delivered

In Queue – Currently in queue trying to be or waiting to be delivered

No Data Available – The tracking database does not know what

happened to this message. Support can check the raw logs if

needed.

Post-Delivery Hard Fail – The message was accepted by the

recipient servers successfully, but we later received a bounce

back email containing a hard failure delivery status (e.g., user

does not exist).

Soft Bounce -- The message was accepted by the recipient

servers successfully, but we later received a bounce back email

containing a soft/temporary failure delivery status (e.g., user’s

disk space is full).

58



details String Information about the status. E.g. “Why is the message queued”

or “What message was returned by the recipient’s server on

successful delivery?”

tls_delivery Integer Value:

1 – TLS was used in the successful delivery to the recipient’s email server.

0 – TLS was not used in the successful delivery

-1 – Unknown or the message was not successfully delivered.

tls_info String For successful deliveries over TLS, this string contains details

about the TLS connection. E.g. ciphers, etc.

to String Single recipient email address for this delivery.



Report: Email URL Clicks

This report allows you to query on the “URL click” events (or lack thereof) for email messages that

have email click tracking enabled. Using this command, it is possible to get a report of all individual

clicks or to get reports about messages that have not yet been clicked on or for which click tracking

was not enabled. See the query parameters for more detail.

Note: if you are using LuxSci Secure Marketing to send your email messages, then normal LuxSci click

and open reporting is disabled (and you will not see click and open data in this report). The LuxSci

Secure Marketing platform his its own click and open tracking and reporting system and you should look

in that interface for reports.

Request Method GET


Request URL Messages sent via SMTP or ActiveSync from email programs and devices:

/perl/api/v2/account/[account id]/report/email/smtp/clicks


/perl/api/v2/account/[account id]/report/email/webmail/clicks

Request Query

String

All standard reporting parameters, plus See Below.


message was sent. This corresponds to the “date_sent” output field.

59



However, if you set the “click_date” input parameter to true, then the

“click_date” field will be used for date selections.

Request Body none



Keyword Data

Type

Description


address

clicked Integer If specified, the results are restricted as follows:

clicked < 0 – select messages where click tracking was not

enabled.

clicked = 0 – select messages where click tracking was enabled,

but where no URLs have yet been clicked by the recipient.

clicked > 0 – select messages where one or more URLs have

been clicked by the recipient. When “clicked” is positive, you will

get one row back for each click; so, you can get multiple rows per

message.

If a value for “clicked” is not specified, a value of “1” will be

assumed.

click_date Boolean If true, the ”click_date” field will be used for all date selections. If

false or not specified, the sent date (“date_sent”) will be used.











60




enabled.

opened = 0 – select messages where open tracking was enabled,

but which have not yet been opened.

opened > 0 – select messages where open tracking was enabled,

and which have been opened at least once.



matching messages.

status Enum Values:

delivered – Accepted by the recipient’s email servers and

presumed delivered. If bounce processing is enabled, then this

status could change later to ba_soft_fail or ba_hard_fail.

perm_fail – Messages that have permanently failed to be delivered

to the recipient’s servers. If bounce processing is on, this status

could change shortly to ba_soft_fail, depending on the nature of

the failure message.

lost – Messages where the tracking was lost and it is unclear if it

was delivered or lost from the queue.

queued – Message is in the email server queue still waiting to be

delivered to the recipient.

not_queued -- all statuses except "queued".

ba_soft_fail – Soft failure bounces received (when talking to the

recipient’s servers or after successful delivery to the recipient’s

servers).

ba_hard_fail – Hard failure bounces received after successful

delivery to the recipient’s servers

any_hard_fail – Results for ba_hard_fail OR perm_fail. I.e., all

hard/permanent failures.

subject String Case-insensitive substring search of the message subject (in UTF-

8).

to String Case-insensitive substring search of all recipient email addresses.



url String Substring match on the URL clicked.

61



JSON Response Body

The header columns in the response include the following (below). Additionally, the 6





HH:MM:SS”.








clicker_ip String IP Address of the person who clicked on the URL at the time of

clicking.

click_date DATETIME The date and time the URL was clicked (in GMT). Format “YYYY-

MM-DD HH:MM:SS”.

user_agent String User Agent string from the program used by the clicker to open the

URL from the message.





In Queue – Currently in queue trying to be or waiting to be

delivered



needed.


recipient servers successfully, but we later received a bounce back

email containing a hard failure delivery status (e.g., user does not

exist).

62





containing a soft/temporary failure delivery status (e.g., user’s disk

space is full).

to String Single recipient email address for this message.

url String The web site address (URL) that was opened.



Report: Email Opens

This report allows you to query on the “opened” events (or lack thereof) for email messages that have

email open tracking enabled. Using this command, it is possible to get a report of all individual opens

for messages or to get reports about messages that have not yet been opened or for which open

tracking was not enabled. See the query parameters for more detail.

Note: if you are using LuxSci Secure Marketing to send your email messages, then normal LuxSci click

and open reporting is disabled (and you will not see click and open data in this report). The LuxSci

Secure Marketing platform his its own click and open tracking and reporting system and you should look

in that interface for reports.

Request Method GET



devices:

/perl/api/v2/account/[account id]/report/email/smtp/opens


/perl/api/v2/account/[account id]/report/email/webmail/opens



message was sent. This corresponds to the “date_sent” output field.

However, if you set the “open_date” input parameter to true, then the

“open_date” field will be used for date selections.

Request Body none


63




Keyword Data

Type

Description


address












enabled.

opened = 0 – select messages where open tracking was enabled,

but which have not yet been opened.

opened > 0 – select messages where open tracking was enabled

and which have been opened at least once. When opened is

positive, you will get one row back for each open; so, you can get

multiple rows per message.

If you do not specify a value for “opened”, a value of “1” will be

assumed.

open_date Boolean If true, the ”open_date” field will be used for all date selections. If

false or not specified, the sent date (“date_sent”) will be used.



matching messages.

64



status Enum Values:

delivered – Accepted by the recipient’s email servers and

presumed delivered. If bounce processing is enabled, then this

status could change later to ba_soft_fail or ba_hard_fail.

perm_fail – messages that have permanently failed to be delivered

to the recipient’s servers. If bounce processing is on, this status

could change shortly to ba_soft_fail, depending on the nature of

the failure message.

lost – messages where the tracking was lost and it is unclear if it

was delivered or lost from the queue.

queued – message is in the email server queue still waiting to be

delivered to the recipient.

ba_soft_fail – Soft failure bounces received (when talking to the

recipient’s servers or after successful delivery to the recipient’s

servers).

ba_hard_fail – Hard failure bounces received after successful

delivery to the recipient’s servers

any_hard_fail – Results for ba_hard_fail OR perm_fail. I.e., all

hard/permanent failures.

subject String Case-insensitive substring search of the message subject (in UTF-

8).




JSON Response Body

The header columns in the response include the following (below). Additionally, the 6





HH:MM:SS”.




65







opener_ip String IP Address of the opening person at the time of opening.

open_date DATETIME The date and time the message was opened (in GMT). Format

“YYYY-MM-DD HH:MM:SS”.

user_agent String User Agent string from the program used by the opener to open the

message.





In Queue – Currently in queue trying to be or waiting to be

delivered



needed.


recipient servers successfully, but we later received a bounce back

email containing a hard failure delivery status (e.g., user does not

exist).



containing a soft/temporary failure delivery status (e.g., user’s disk

space is full).

to String Single recipient email address for this message.



Report: SMTP Login Failures / Rejections

This report allows to see all SMTP login failures, as well as sending errors that resulted from our

servers explicitly rejecting your request to send an email message for one reason or another.

66



Request Method GET


Request URL /perl/api/v2/account/[account id]/report/login_fail/smtp


Request Body none




ip String Case-insensitive substring search of the message “IP Address” if

the email program or device that made the connection.

Reason String Case-insensitive substring search of the login failure / reason data.

JSON Response Body



date DATETIME When the failure or rejection happened.

ip String IP Address of the device or program that tried to login and send.

reason String Description of why the login failed or the message send was rejected.


Report: Email Feed Back Loops

This report allows to see what messages that you have sent successfully have been “marked as

spam” by recipients and this information has come back to us via one of our feedback loops.

Request Method GET


Request URL /perl/api/v2/account/[account id]/report/email/fbl


67



Request Body none




from String Case-insensitive substring search of the message “From” email address

subject String Case-insensitive substring search of the message subject (in UTF-8).



JSON Response Body



complaint_date DATETIME When the feedback loop complaint was received.

complaint_source String Name of the ISP where the complaint originated. E.g. “AOL”.

date_sent DATETIME When the message was sent In GMT. Format “YYYY-MM-DD

HH:MM:SS”.

message_type String Description of how the message was sent. I.e. what sending

method.

sendmail_id String Unique sendail_id of this message; useful for tracking

purposes.

server_ip String IP Address of the sending server.

subject String Subject of the message that was sent.

to String Single recipient email address for this delivery. This is the

recipient who complained. This could be the word “redacted”, if

the ISP of the recipient does not publish who is complaining

(e.g. all complaints from AOL have the email address of the

complainer redacted).



68



Servers

For customers with one or more dedicated servers, there are a number of API commands that are

useful for querying the state of these servers.

List of All Servers

This report allows you to retrieve general information about all of the dedicated servers associated

with your account.

Request Method GET

Access Required Account: Servers - Report

Request URL /perl/api/v2/account/[account id]/servers


Request Body none

Success Response List of servers. See below. This list will be empty if your account does

not have any dedicated servers.

JSON Response Body

The data field in the JSON response is a list of hashes, one for every server. The hash of data for

each server will contain the following keywords.


server_id Integer Unique server ID number.

host String Short name for your server. E.g., “rs999”.

hostname String Fully qualified name for your server. E.g., “rs999.luxsci.com”.

cpu_cores Integer Number of CPU Cores.

ram_gb Integer Number of GB of Physical Ram.

premium_sla Boolean If true (1), this server is flagged as obeying LuxSci’s “Premium

SLA”.

load_balanced Boolean If true (1), this server is flagged as being part of a hardware load

balanced group of servers.

public_ip String The main public IP address for this server.

69



server_type_code String This is a code of the format “X-A-B.extra” that uniquely identifies

the kind of server that this is. A = CPU Cores; B = GB Ram;

“extra” is used for AWS servers to indetify their flavor. X is one

of:

• r – Rackspace Public Cloud behind hardware firewalls

• a – AWS Public Cloud

• e – Enterprise Class Rackspace Private Cloud

• p – Physical Server

• g – General / other.

Servers Status

This report allows you to retrieve specific current status of a specific server. This request will actually

directly interrogate the server for some of this information; in situations where the server is overloaded

or down or very slow, this API will fail.

The “server_id” parameter in the Request URL should be the numeric “server_id” returned by the

“Server List” API call, above. However, it can also be the short host name. I.e., if server with host

“rs999” has a server_id of “197890” … you can use either “197890” or “rs999” as the “server_id”.

Request Method GET

Access Required Account: Servers - Report

Request URL /perl/api/v2/account/[account id]/server/server_id


Request Body none

Success Response Server information. See below.

70



JSON Response Body

The data field in the JSON response has all of the keywords defined in the “Server List” command,

above, as well as the following additional keywords.


cpu_pct_load_1 Integer Percentage CPU utilization per core over the past 1

minute. This is derived from the Linux “uptime”

command and is computed as the “(1-minute load

average) * 100% / (CPU Cores)”


minutes.


minutes.

seconds_since_reboot Integer Number of seconds since the server was last

rebooted. This is derived from the “uptime” Linux

command.

ram_free_mb Integer Megabyes of RAM still available for use. This does not

include swap space but does include used cache and

buffer space.

ram_pct_used Integer Percentage of the RAM that is used, based on

ram_free_mb and ram_gb

swap_mb Integer MB of SWAP space that the server has

swap_free_mb Integer MB of SWAP space that is not used.

swap_pct_used Integer Percentage of the SWAP space that is in use.

bw_in_mb Float MB of inbound bandwidth, across all protocols,

recorded over the most recent 15-minute interval.

bw_out_mb Float MB of outbound bandwidth, across all protocols,

recorded over the most recent 15-minute interval.

bw_in_rate_mbps Float Megabytes/second of average sustained inbound

bandwidth observed over the most recent 15-minute

interval.

Bw_out_rate_mbps Float Megabytes/second of average sustained outbound

bandwidth observed over the most recent 15-minute

interval.

71



mail_queue_unprocessed Integer Number of email messages that have been received,

but which are waiting to be processed (i.e., for

encryption or other activities) before being re-queued

for delivery to their ultimate recipients. Note: if you

have delivery rate limiting on, messages that are not

being delivered due to rate limiting will show as

“unprocessed”.

mail_queue_trying Integer Number of email messages that are in the email

queues waiting to be delivered to their ultimate

recipients. This includes messages that have tried

and failed to be delivered due to temporary failures or

blocks.

disks Array This is an array of hashes, one for each mount point

on the server. The hashes for each mount point

include the following keywords:

• mount – the name of the mount point

• size_mb – the size of the disk in MB

• used_mb – the space used in MB

• io_used_pct – the disk IO utilization percentage.

When this is high, processes that read and write to

the drive will be slower.

Have Additional Questions? We’re Happy to Help!

Call: +1 800-441-6612

Email: [email protected]

Web: luxsci.com

Solutions to Ensure Your Private Information Stays Private:

• Secure Email Marketing • Secure High Volume Sending

Secure Connector • Secure Email Hosting

• Secure Web Hosting

• Secure Web & PDF Forms

• Secure Text

LuxSci is your trusted leader for secure email, data and communication solutions.

LuxSci helps ensure that “what’s private stays private.” Find out why LuxSci is the

go-to source by the nation’s most influential institutions in healthcare, finance and

government for comprehensive, flexible, and easy-to-use secure solutions.


LUXSCI API v2 · 2020. 11. 20. · 6 LuxSci API v2: Mechanics luxsci.com Keyword Value custom1...

Documents

Transcript of LUXSCI API v2 · 2020. 11. 20. · 6 LuxSci API v2: Mechanics luxsci.com Keyword Value custom1...