luxsci api v2 · 2020. 11. 20. · 6 luxsci api v2: mechanics luxsci.com keyword value custom1...
TRANSCRIPT
luxsci.com Last Updated: , 2021 for LuxSci v2021.2.4
LUXSCI API v2 Account Functions
by Erik Kangas, PhD
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Keyword Value
custom1 Custom field #1
custom2 Custom field #2
custom3 Custom field #3
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Query String none
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.
Keyword Data Type Description
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”
9
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/46792/users/[email protected]
Content-Type: application/json
{“disk_quota”: 0.75 }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
10
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Request Query String none
Request Body See below
Success Response none
JSON Request Body
The Request body contains only 1 required field
Keyword Data Type Description
new_address Email address Required. The new login username (email address) for this user.
11
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/46792/users/[email protected]/rename
Content-Type: application/json
{“new_address”: “[email protected]”}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
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
Request Query String none
Request Body See below
Success Response See below
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
Keyword Data Type Description
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
Keyword Data Type Description
uid Integer The new user’s unique user ID.
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/73462/users
Content-Type: application/json
{“password”:”I L0v3 P1zza”, user: “[email protected]”, contact: “John Sample”}
13
LuxSci API v2: Mechanics
luxsci.com luxsci.com
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
Request Query String none
Request Body See below
Success Response See below
JSON Request Body
The Request body contains the following settings for the new domain.
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Keyword Data Type Description
Id Integer The new domain’s unique user ID.
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/73462/domains
Content-Type: application/json
{“domain_name”: “sample-domain.com”, “accept_mail”: 1}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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 Method DELETE
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/domains/[domain_name]
15
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Query String none
Request Body none
Success Response none
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/domains/sample-domain.com
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
Update Domain
Change selected domain settings.
Request Method PUT
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/domains/[domain name]
Request Query String none
Request Body See below
Success Response none
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.
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/73462/domains/sample-domain.com
Content-Type: application/json
{“catchall_on”: 1, catchall_action: “email”, “catchall_data”: “[email protected], someone
[email protected]”, “accept_mail”: 1}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
17
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Get Domains Report
Get information about your domains
Request Method GET
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/domains
Request Query String none
Request Body none
Success Response See below
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:
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/domains
Content-Type: application/json
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/domains/[domain name]
Request Query String none
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/domains/my-secure-domain.com
Content-Type: application/json
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
DKIM Requests
Create DKIM
Create a new DKIM configuration in your account.
Request Method POST
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/dkim
Request Query String none
Request Body none
Success Response See below
JSON Request Body
The Request body contains the following settings for the new domain.
Keyword Data Type Description
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.
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/73462/dkim
Content-Type: application/json
{“domain”: “sample-domain.com”}
20
LuxSci API v2: Mechanics
luxsci.com luxsci.com
HTTP/1.1 200 OK
Delete DKIM
Remove a DKIM definition from your account.
Request Method DELETE
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/dkim/[domain_name]
Request Query String none
Request Body none
Success Response none
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/dkim/sample-domain.com
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
Get DKIM Report
Get information about your DKIM configurations
Request Method GET
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/dkim
Request Query String none
Request Body none
Success Response See below
21
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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:
Keyword Data Type Description
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
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/dkim/[domain name]
Request Query String none
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/dkim/my-secure-domain.com
Content-Type: application/json
22
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Request Query String none
Request Body See below
Success Response No body returned.
JSON Request Body
Keyword Data Type Description
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.
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/73462/suppression
Content-Type: application/json
{“emails": "[email protected],[email protected]", expires: 30}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
23
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Delete Suppression
Delete a specific account-level email suppression.
Request Method DELETE
Access Required User Email: Suppression
Request URL /perl/api/v2/account/[account id]/suppression/email
Request Query String none
Request Body none
Success Response No body returned.
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/suppression/[email protected]
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
Get Suppression
Retrieve a specific email suppression at the account level.
Request Method DELETE
Access Required User Email: Suppression
Request URL /perl/api/v2/account/[account id]/suppression[/email]
Request Query String none
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/suppression/[email protected]
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Request Query String none
Request Body See below
Success Response See below
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.
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
JSON Response
Keyword Data Type Description
added Integer Number of new aliases that were created (e.g. for validation
purposes).
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/73462/aliases
Content-Type: application/json
{“aliases”: [{“user”:”john”, “domain”:“sample.com”, “action”: “bounce”, “bounce”: “Address no longer
valid.” }]}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
Access Required Account: Alias Management
Request URL /perl/api/v2/account/[account id]/aliases/[alias address]
Request Query String None
Request Body See below
Success Response None
JSON Request Body
The Request body contains the following settings for updating an email alias.
27
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Keyword Data Type Description
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.
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]
Content-Type: application/json
{ “action”: “email”, “dest”: “[email protected], [email protected]”, “status”: “enabled”}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
Delete Alias
Remove an alias with the specified alias email address from your account.
Request Method DELETE
Access Required Account: Domain Management
Request URL /perl/api/v2/account/[account id]/aliases/[alias address]
Request Query String none
Request Body none
28
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Success Response none
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
Get Aliases Report
Get information about your email aliases including regular aliases, user forwards, domain catchalls,
and WebAide Group distribution lists.
Request Method GET
Access Required Account: Alias Management
Request URL /perl/api/v2/account/[account id]/aliases
Request Query String none
Request Body none
Success Response See below
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:
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/aliases
Content-Type: application/json
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Access Required Account: Alias Management
Request URL /perl/api/v2/account/[account id]/aliases/[alias address]
Request Query String none
Request Body none
Success Response See below
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/aliases/[email protected]
Content-Type: application/json
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request URL /perl/api/v2/account/[account id]/secureforms
Request Query String none
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:
Keyword Data Type Description
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):
• 2col – Two-column HTML view of keywords and values
• csv – CSV file
• html – Custom re-filled HTML template
• pdf – Custom re-filled PDF template
32
LuxSci API v2: Mechanics
luxsci.com luxsci.com
• 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
ftp_content Set What will be uploaded to FTP/SFTP? This is a comma- delimited list of data types (posted files are always uploaded):
• 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
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
Access Required Account: SecureForm Configuration
Request URL /perl/api/v2/account/[account id]/secureforms/ID
Request Query String none
Request Body none
Success Response see below
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
34
LuxSci API v2: Mechanics
luxsci.com luxsci.com
{“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
Access Required Account: SecureForm Configuration
Account: SecureForm Database Read
Request URL /perl/api/v2/account/[account id]/secureforms/ID/db
Request Query String see below
Request Body none
Success Response see below
Request Query String
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).
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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:
Keyword Data Type Description
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db?after_index=10
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Access Required Account: SecureForm Configuration
Account: SecureForm Database Read
Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/rows
Request Query String see below
Request Body none
Success Response see below
Request Query String
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
__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.
Example (cookie omitted)
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
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Access Required Account: SecureForm Configuration
Account: SecureForm Database Read
Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/INDEX
Request Query String none
Request Body none
Success Response see below
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.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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.
This API call is audited: a record will be made of the particular API Integration and IP address that
“deleted” each matching row (also implying that any associated files have been removed).
39
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Method Delete
Access Required
Account: SecureForm Configuration
Account: SecureForm Database Read
Account: SecureForm Database Delete
Request URL /perl/api/v2/account/[account id]/secureforms/ID/db/INDEX
Request Query String none
Request Body none
Success Response standard simple response
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
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.
This API call is audited: a record will be made of the particular API Integration and IP address that
“read” each file.
Request Method GET
Access Required Account: SecureForm Configuration
Account: SecureForm Database Read
Request URL /perl/api/v2/account/[account
id]/secureforms/ID/db/ROW_INDEX/file/FILE_INDEX
Request Query String none
Request Body none
Success Response see below
40
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13/file/179
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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).
This API call is audited: a record will be made of the particular API Integration and IP address that
deleted each file.
Request Method DELETE
Access Required Account: SecureForm Configuration
Account: SecureForm Database Read
Account: SecureForm Database Delete
Request URL /perl/api/v2/account/[account
id]/secureforms/ID/db/ROW_INDEX/file/FILE_INDEX
41
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Query String none
Request Body none
Success Response standard
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/secureforms/6895/db/13/file/179
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Access Required SecureSend NameSpace Management
Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace
id]/users/[username]
Request Query String none
Request Body See below
Success Response Standard simple success
JSON Request Body
The Request body contains the following settings.
Keyword Data Type Description
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
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/[email protected]
Content-Type: application/json
{ “name”: “John Sample”, “timezone”: “EST5EDT”, “password”: “slkjf656g!” }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
43
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Access Required SecureSend NameSpace Management
Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace
id]/users/[username]/password
Request Query String none
Request Body See below
Success Response Standard simple success
JSON Request Body
The Request body contains the following settings.
Keyword Data Type Description
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.
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/john@sample.
com/password
Content-Type: application/json
{ “password”: “slkjf656g!” }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
44
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Access Required SecureSend NameSpace Management
SecureSend Single sign-On
Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace
id]/users/[username]/password
Request Query String See below
Request Body none
Success Response See below
Query String
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Not that the SecureSend NameSpace specified must be
associated with this Theme, or the API will return an error.
Result
This returns the URL.
Keyword Data Type Description
url String URL for the end user to go to so that s/he can login to SecureSend without a username or password.
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users/john@sample.
com/password
Content-Type: application/json
{ ip: “5.33.44.1”, theme: 1788906572 }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
Access Required SecureSend NameSpace Management
Request URL /perl/api/v2/account/[account id]/pl/namespaces/[namespace id]/users
Request Query String none
Request Body none
Success Response See below
46
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Result
This returns a list of objects. The objects will have keys with values as described, below:
Keyword Data Type Description
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
Example (cookie omitted)
GET https://rest.luxsci.com/perl/api/v2/account/73462/pl/namespaces/37/users
Content-Type: application/json
{ ip: “5.33.44.1”, theme: 1788906572 }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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:
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
• 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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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:
Keyword Data Type Description
date_sent DATETIME When the message was sent In GMT. Format “YYYY-MM-DD
HH:MM:SS”.
52
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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 usage not recorded for some reason
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
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/delivery
Messages sent via WebMail
/perl/api/v2/account/[account id]/report/email/webmail/delivery
Request Query String All standard reporting parameters, plus See Below.
Dates, for the purposes of narrowing results, refer to the date the
message delivery status was last updated. This corresponds to the
“last_update” output field.
Request Body none
Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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”
header2 String See: “Report: Email Sent”
header2_operator Enum See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_operator Enum See: “Report: Email Sent”
header3_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 usage not recorded for some reason
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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”).
Keyword Data Type Description
date_sent DATETIME When the message was sent (in GMT). Format “YYYY-MM-DD
HH:MM:SS”.
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 See: “Report: Email Sent”
header1_value String See: “Report: Email Sent”
header2 String See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_value String See: “Report: Email Sent”
57
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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 usage not recorded for some reason
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
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 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
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/clicks
Messages sent via WebMail
/perl/api/v2/account/[account id]/report/email/webmail/clicks
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. This corresponds to the “date_sent” output field.
59
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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
Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
Keyword Data
Type
Description
from String Case-insensitive substring search of the message “From” email
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.
header1 String See: “Report: Email Sent”
header1_operator Enum See: “Report: Email Sent”
header1_value String See: “Report: Email Sent”
header2 String See: “Report: Email Sent”
header2_operator Enum See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_operator Enum See: “Report: Email Sent”
header3_value String See: “Report: Email Sent”
opened Integer If specified, the results are restricted as follows:
60
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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 once.
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.
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.
tracked_headers Boolean See: “Report: Email Sent”
user_id Integer Restrict the report to the user with this specific User ID number.
url String Substring match on the URL clicked.
61
LuxSci API v2: Mechanics
luxsci.com luxsci.com
JSON Response Body
The header columns in the response include the following (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”).
Keyword Data Type Description
date_sent DATETIME When the message was sent (in GMT). Format “YYYY-MM-DD
HH:MM:SS”.
from String From email address
header1 String See: “Report: Email Sent”
header1_value String See: “Report: Email Sent”
header2 String See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_value String See: “Report: Email Sent”
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.
sendmail_id String Unique sendmail_id of this message; useful for tracking purposes.
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).
62
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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).
to String Single recipient email address for this message.
url String The web site address (URL) that was opened.
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 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
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/opens
Messages sent via WebMail
/perl/api/v2/account/[account id]/report/email/webmail/opens
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. 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
Success Response Standard response for all reports. Data field details listed below.
63
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Additional Query String Parameters
Keyword Data
Type
Description
from String Case-insensitive substring search of the message “From” email
address
header1 String See: “Report: Email Sent”
header1_operator Enum See: “Report: Email Sent”
header1_value String See: “Report: Email Sent”
header2 String See: “Report: Email Sent”
header2_operator Enum See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_operator Enum See: “Report: Email Sent”
header3_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 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.
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.
64
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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).
to String Case-insensitive substring search of all recipient email addresses.
tracked_headers Boolean See: “Report: Email Sent”
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 (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”).
Keyword Data Type Description
date_sent DATETIME When the message was sent (in GMT). Format “YYYY-MM-DD
HH:MM:SS”.
from String From email address
header1 String See: “Report: Email Sent”
header1_value String See: “Report: Email Sent”
65
LuxSci API v2: Mechanics
luxsci.com luxsci.com
header2 String See: “Report: Email Sent”
header2_value String See: “Report: Email Sent”
header3 String See: “Report: Email Sent”
header3_value String See: “Report: Email Sent”
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.
sendmail_id String Unique sendmail_id of this message; useful for tracking purposes.
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).
to String Single recipient email address for this message.
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: 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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Method GET
Access Required Account: View Reports
Request URL /perl/api/v2/account/[account id]/report/login_fail/smtp
Request Query String All standard reporting parameters, plus See Below.
Request Body none
Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
Keyword Data Type Description
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
The header columns in the response include the following:
Keyword Data Type Description
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.
user_id Integer User ID of the user who sent the message
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
Access Required Account: View Reports
Request URL /perl/api/v2/account/[account id]/report/email/fbl
Request Query String All standard reporting parameters, plus See Below.
67
LuxSci API v2: Mechanics
luxsci.com luxsci.com
Request Body none
Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
Keyword Data Type Description
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).
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:
Keyword Data Type Description
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).
user String Login mail address of the user who sent the message
user_id Integer User ID of the user who sent the message
68
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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 Query String none
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.
Keyword Data Type Description
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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 Query String none
Request Body none
Success Response Server information. See below.
70
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.
Keyword Data Type Description
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)”
cpu_pct_load_5 Integer Percentage CPU utilization per core over the past 5
minutes.
cpu_pct_load_10 Integer Percentage CPU utilization per core over the past 15
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
LuxSci API v2: Mechanics
luxsci.com luxsci.com
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.