LUXSCI API V2 ACCOUNT FUNCTIONS - BY ERIK KANGAS, PHD WWW.LUXSCI.COM
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
LUXSCI API v2
Account Functions
by Erik Kangas, PhD
www.luxsci.com
Last Updated: , 2021 for LuxSci v2021.2.4
luxsci.com
2 LuxSci API v2: Mechanics
TABLE OF CONTENTS
OVERVIEW ...................................................... 3 Delete Alias ................................................... 27
Get Aliases Report ......................................... 28
Account API Access Controls ...................... 3
Get Alias Details ............................................ 29
LuxSci Secure Marketing Requests ............ 4
SecureForm Management ........................... 30
User Management Requests......................... 4 Get SecureForm List ...................................... 30
Get User Report ............................................... 5
Get SecureForm ............................................ 33
Delete User ...................................................... 7
Get SecureForm Database Rows.................. 35
Update User Settings..................................... 7 Get SecureForm Database Row ................... 37
Rename User ................................................. 10 Delete SecureForm Database Row ............... 38
Create User .................................................... 11 Get SecureForm Database File ..................... 39
Domain Management Requests ................. 13 Delete SecureForm Database File ................ 40
Create Domain ............................................... 13 SecureSend NameSpace Management ..... 41
Delete Domain ............................................... 14 Create/Update SecureSend User .................. 41
Update Domain .............................................. 15 Change SecureSend User Password ............ 43
Get Domains Report ...................................... 17 Get SecureSend User Single Sign-On Link .. 44
Get Domain Details ........................................ 18 Get SecureSend User List ............................. 45
DKIM Requests ............................................. 19 Reports .......................................................... 46
Create DKIM .................................................. 19 Report Querying and Results:
Delete DKIM ................................................... 20 Commonalities ............................................... 47
Get DKIM Report............................................ 20 Report: Email Sent ......................................... 48
Get DKIM Details ........................................... 21 Report: Email Delivery Status........................ 53
Email Suppression....................................... 22 Report: Email URL Clicks .............................. 58
Create Suppression ....................................... 22 Report: Email Opens...................................... 62
Delete Suppression........................................ 23 Report: SMTP Login Failures / Rejections .... 65
Get Suppression ............................................ 23 Report: Email Feed Back Loops .................... 66
Email Alias Management Requests ........... 24 Servers .......................................................... 68
Create Alias.................................................... 24 List of All Servers ........................................... 68
Update Alias ................................................... 26 Servers Status ............................................... 69
luxsci.comLuxSci API v2: Mechanics 3
OVERVIEW
The “account” API scope allows your API client to access manage users, domains, email aliases, and
other account-level properties. Some user management tasks would be performed using “user” scope
(e.g. changing a user’s password); account-scope commands are more administrative and include
commands that would not be appropriate for a user to perform him/herself. You can access
commands in account scope:
• An API Integration whose “scope” is set to “account” (or higher) and where you have enabled
access control for the groups of account-level commands that you wish to perform.
Note that API credentials with account scope (or higher) do not need additional usernames or
passwords to perform commands. You must protect your API keys, as compromised keys will allow
others to perform any of the commands permitted to your API Integration. We also recommend that
you permit only specific IP addresses to use your API credentials.
All account requests have API URLS that start with:
/perl/v2/api/account/[ID]
where “ID” is the account unique ID number of the account with respect to which the command will
apply.
Account API Access Controls
The account API scope has a number of access controls that govern which commands your API is
allowed to perform. None of these commands is enabled by default – so your API can only execute
API commands that you have explicitly opted into. This table lists the available account- scope API
Access controls. As more commands are added in the future, they will either fall naturally into one of
these existing access groups, or new access groups will be added to cover them. Your API Interface
should not gain significant additional system access or control when new commands are added to the
API in the future; you will need to explicitly opt into use of any new functionality, should you decide
that your API client requires it.
luxsci.com4 LuxSci API v2: Mechanics
Account-Scope Access Control Notes
General
“Permit user-level commands without username and
password”
User Scope This allows your API Integration to perform user-scope
commands on allowed users without also supplying their
usernames and passwords.
“Permit auto-upgrades as needed to fulfill requests” Allows
Upgrades the system to automatically upgrade your account, if needed,
in order to perform API commands such as “add user”.
Permit domain management commands such as get domain
Manage Domains details, add domain, delete domain, update domain, manage
DKIM.
Permit alias management commands such as get alias
Manage Aliases
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.
luxsci.comLuxSci API v2: Mechanics 5
Get User Report
Return an array of information about all users matching your query request.
Request Method GET
Access Required User Settings: Read access
Request URL /perl/api/v2/account/[account id]/users
Request Query String See below
Request Body none
Success Response See below
Request Query String
The Request query string can contain any or all of the following keywords parameters to refine the
search. If all are omitted, the report will include information about all users in the account. In all cases,
any users protected from API access will not be included in the report.
Keyword Data Type Description
status Enum Value ‘enabled’ – return only active/enabled users.
Value ‘disabled’ – return only disabled users.
domain String Domain name in your account. If supplied, only users in this
domain will be returned.
younger_than Integer Return only users created less than this number of days ago.
older_than Integer Return only users created more than this number of days ago.
JSON Response
The successful response will be an array of objects, one for each matching user in your account. Each
user object returned will have the following keywords / values:
Keyword Value
city City
company Company / organization
contact Full name. E.g. “John Smith”
country Country
created Date and time this user was created (YYYY-MM-DD HH:MM:SS in GMT)
luxsci.com6 LuxSci API v2: Mechanics
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 Time the user last logged into any of WebMail, POP, IMAP, or SMTP (not
date 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. joe@doman.com)
zip Zip / postal code
luxsci.comLuxSci API v2: Mechanics 7
Delete User
Delete the user from the system. This eliminates all the user’s data, history, web/ftp files and email.
After this command is complete, there will no longer be any record that the user existed.
This command cannot be undone.
Note that some users cannot be deleted in this way. For example, any user with “account
management” permission cannot be deleted. Other users may not be able to be deleted if there are
things in your account (e.g. web sites) that are still owned by them. You will receive an error if you try
to delete a user that is not currently deletable.
Note that deletion of a user does not downgrade your account. Please contact billing for account
downgrade requests.
Request Method DELETE
Access Required Enable / Disable / Delete Users
Request URL /perl/api/v2/account/[account id]/users/[username]
Request Query String none
Request Body none
Success Response nothing extra
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/49721/users/john@doctor.com
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]
luxsci.com8 LuxSci API v2: Mechanics
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_ User Name Pass the user name of another user in this account (e.g.
preferences_ “john@domain.com”). Web Interface preferences will be
from 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”
luxsci.comLuxSci API v2: Mechanics 9
Only currently-enabled users can be disabled.
disk_quota Floating Point Set a new hard total disk quota for this user. The value passed
should be in Gigabytes. E.g. a value of 0.5 would set the limit
to 500 MB. A value of zero is not permitted. A negative value
will clear the disk quota ... resulting in the user no longer
having a disk space limit (which is the default for all users).
Disk space is measured hourly. If the user’s individual disk
usage (the sum of all disk space used by email, web, ftp,
WebAides, etc.) exceeds his/her disk space quota, then many
services will be explicitly disabled and incoming email will
bounce. Since the disk usage is only checked hourly, it is
possible that the user’s disk space usage will exceed the quota
before the user’s account is suspended.
enable Integer If a “1” is passed, then the user will be re-enabled. Requires
access: “Account: Enable/Disable/Delete users”
Only currently-disabled users can be enabled.
remove_flag flag_name Remove a flag from the user.
remove_service service_name Remove the specified service from the user.
set_flag flag_name Enable the specified flag on this user. Valid flags include:
• “poor_password” – User must change his/her password on
the next login to the Web Interface
• “can_autodelete” – User account can be auto-deleted if the
user has not logged in in a long time
Example (cookie omitted)
PUT https://rest.luxsci.com/perl/api/v2/account/46792/users/user@doctor.com
Content-Type: application/json
{“disk_quota”: 0.75 }
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
luxsci.com10 LuxSci API v2: Mechanics
Rename User
Change the user’s login email address from [username] to [new_address]. E.g. change
“john@sample. com” to “fred@newdomain.com”. 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.
luxsci.comLuxSci API v2: Mechanics 11
Example (cookie omitted)
POST https://rest.luxsci.com/perl/api/v2/account/46792/users/john@sample.com/rename
Content-Type: application/json
{“new_address”: “fred@newdomain.com”}
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).
luxsci.com12 LuxSci API v2: Mechanics
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. “john@domain.com”. The
domain name used must already be an active domain in your
account.
basic_spam_ Integer Optional. If this is specified and its value is true (e.g. 1) AND
filter 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: “test@somedomain.com”, contact: “John Sample”}
luxsci.comLuxSci API v2: Mechanics 13
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).
luxsci.com14 LuxSci API v2: Mechanics
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]
luxsci.comLuxSci API v2: Mechanics 15
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.
luxsci.com16 LuxSci API v2: Mechanics
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”: “admin@mydomain.com, someone
else@another.com”, “accept_mail”: 1}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1 }
luxsci.comLuxSci API v2: Mechanics 17
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
“1” if the domain is globally enabled and receipt of inbound
accept_mail Boolean
email is also enabled. Otherwise, “0”.
Date and time the domain was created (added to this system).
created DATETIME
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.
“1” if the domain’s ownership has been verified for this
account (e.g. by making the proper DNS changes). “0” if
is_verified Boolean
not. Inbound
email will be rejected for domains that are not verified.
Number of users in the domain with licenses for
msync_users Integer
MobileSync.
secureline_
Integer Number of users in the domain with licenses for SecureLine.
users
users Integer Number of users in this domain
luxsci.com18 LuxSci API v2: Mechanics
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}}
luxsci.comLuxSci API v2: Mechanics 19
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”}
luxsci.com20 LuxSci API v2: Mechanics
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
luxsci.comLuxSci API v2: Mechanics 21
JSON Response Body
The data field of the response is an array of all DKIM definitions in your account. Each entry in the
array is an object containing the following keyword and values:
Keyword Data Type Description
domain String Domain name the definition applies to.
Date and time the definition was created (added to this
created DATETIME
system). Format: “YYYY-MM-DD HH:MM:SS” in GMT
selector String DKIM selector
Main DNS text record to add to implement the DKIM. Other
dns String 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
luxsci.com22 LuxSci API v2: Mechanics
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": "test1@domain.com,test2@domain.com", expires: 30}
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1}
luxsci.comLuxSci API v2: Mechanics 23
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/test1@domain.com
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.
luxsci.com24 LuxSci API v2: Mechanics
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/test1@domain.com
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1, data: [[ "test1@domain.com", 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.
luxsci.comLuxSci API v2: Mechanics 25
Note also that accounts are limited in the maximum number of email aliases permitted per domain. By
default, this is 100 + 10 aliases per user in the domain. So, for a domain with 20 users, this would be
100 + 10x20 = 300 aliases.
Request Method POST
Access Required Account: Alias Management
Request URL /perl/api/v2/account/[account id]/aliases
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 “john@sample.com”. 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”
luxsci.com26 LuxSci API v2: Mechanics
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.
luxsci.comLuxSci API v2: Mechanics 27
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/info@doctor.com
Content-Type: application/json
{ “action”: “email”, “dest”: “dr.smith@doctor.com, dr.jones@doctor.com”, “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
luxsci.com28 LuxSci API v2: Mechanics
Success Response none
Example (cookie omitted)
DELETE https://rest.luxsci.com/perl/api/v2/account/73462/aliases/john@sample.com
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
luxsci.comLuxSci API v2: Mechanics 29
creation times started to be tracked). These will return a
created value of “0000-00-00 00:00:00”.
dest Email List For aliases whose action is “email”, this is the comma-
delimited list of destination email addresses
distribution_ String For aliases whose type is “distribution”, this is the name of
list_group the WebAide Group.
domain String Domain name (e.g. for alias “john@sample.com”, this would
be “sample.com”)
msync_users Integer Number of users in the domain with licenses for MobileSync.
secureline_
Integer Number of users in the domain with licenses for SecureLine.
users
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: ‘other@address.com’, 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
luxsci.com30 LuxSci API v2: Mechanics
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/john@sample.com
Content-Type: application/json
HTTP/1.1 200 OK
Pragma: no-cache
Content-Type: application/json
{“auth”: [omitted],”success”:1, data: {bounce: null, dest: ‘other@address.com’, 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
luxsci.comLuxSci API v2: Mechanics 31
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
luxsci.com32 LuxSci API v2: Mechanics
• 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
luxsci.comLuxSci API v2: Mechanics 33
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
luxsci.com34 LuxSci API v2: Mechanics
{“auth”: [omitted],”success”:1 , data: { ‘archive_content’: ‘csv’, ‘status’: 1, ‘secure’: 1, ‘ftp_content’: null,
‘modified’: ‘2015-02-07 16:25:44’, ‘mysql_encrypt’: 1, ‘last_post’: ‘2015-05-01 11:33:17’, ‘notes’: null,
‘email_content’: ‘text,pdf’, ‘action’: ‘email_data,mysql’, ‘type’: ‘pdf’, ‘title’: ‘My Example Form’, ‘id’:
2567981, db_host: ‘mysql55.web10.luxsci.com’, db_name: ‘dr_office_db’, db_table: “intake_forms” }}
Get SecureForm Database Info
Returns details on the posts currently stored in the database table associated with a specific
SecureForm configuration. This function is recommended for use when synchronizing or periodically
downloading new rows to an external source: it allows you to quickly and easily see what, if any,
entries are new relative to your last actions (if you saved the last index or date when you previously
downloaded data).
Request Method GET
Account: SecureForm Configuration
Access Required
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
All rows added after the specified date time (in GMT,
after_date DATETIME
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
luxsci.comLuxSci API v2: Mechanics 35
All rows whose index is greater than or equal to the
from_index Integer
specified value.
through_date DATETIME All rows added on or before the specified date time
All rows whose index is less than or equal to the specified
through_index Integer
value.
JSON Response Body
The Response Body contains a “data” object with keywords and values. These are:
Keyword Data Type Description
Date when the oldest matching row was added (in GMT,
oldest_post DATETIME
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
luxsci.com36 LuxSci API v2: Mechanics
Account: SecureForm Configuration
Access Required
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.
luxsci.comYou can also read
