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.com
LuxSci 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.com
4 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.com
LuxSci 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.com
6 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. [email protected]) zip Zip / postal code
luxsci.com
LuxSci 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/[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]
luxsci.com
8 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_ “[email protected]”). 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.com
LuxSci 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/[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 }
luxsci.com
10 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 “[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.
luxsci.com
LuxSci API v2: Mechanics 11
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).
luxsci.com
12 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. “[email protected]”. 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: “[email protected]”, contact: “John Sample”}
luxsci.com
LuxSci 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.com
14 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.com
LuxSci 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.com
16 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”: “[email protected], someone [email protected]”, “accept_mail”: 1}
HTTP/1.1 200 OK Pragma: no-cache Content-Type: application/json {“auth”: [omitted],”success”:1 }
luxsci.com
LuxSci 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.com
18 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.com
LuxSci 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.com
20 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.com
LuxSci 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.com
22 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": "[email protected],[email protected]", expires: 30}
HTTP/1.1 200 OK Pragma: no-cache Content-Type: application/json {“auth”: [omitted],”success”:1}
luxsci.com
LuxSci 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/[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.
luxsci.com
24 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/[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.
luxsci.com
LuxSci 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 “[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”
luxsci.com
26 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.com
LuxSci 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/[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
luxsci.com
28 LuxSci API v2: Mechanics
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
luxsci.com
LuxSci 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 “[email protected]”, 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: ‘[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
luxsci.com
30 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/[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
luxsci.com
LuxSci 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.com
32 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.com
LuxSci 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.com
34 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.com
LuxSci 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.com
36 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.com
LuxSci API v2: Mechanics 37
__files__ Array An array of file information that can be used to manipulate the files associated with this post/row. Each item in this array is an object representing one of the associated files. The keywords in these objects are: • file_id – Unique (integer) ID for this file • size – Size in bytes of this file • name – Filename for this file __index__ Integer Unique index for this form post / database row. __ip_address__ String IP Address of the computer used by the end user who submitted this form post. __n_files__ Integer The number of files associated with this post/row that are currently saved in the database. __posted__ DATETIME Date and time the data was saved to this database table in GMT (format “YYYY-MM-DD HH:MM:SS”) __referrer__ String HTTP Referer passed by the end user’s web client.
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.
luxsci.com
38 LuxSci API v2: Mechanics
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 Account: SecureForm Configuration Access Required 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).
luxsci.com
LuxSci API v2: Mechanics 39
Request Method Delete Account: SecureForm Configuration Access Required 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 Account: SecureForm Configuration Access Required Account: SecureForm Database Read /perl/api/v2/account/[account Request URL id]/secureforms/ID/db/ROW_INDEX/file/FILE_INDEX Request Query String none Request Body none Success Response see below
luxsci.com
40 LuxSci API v2: Mechanics
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. BASE64-encoded file data. If you decode this, you will have the raw file_base64 file content. name The file’s name. size Size in bytes of the raw file (un-encoded). DATETIME (in GMT, the usual format) when the file was uploaded/ 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
luxsci.com
LuxSci API v2: Mechanics 41
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
luxsci.com
42 LuxSci API v2: Mechanics
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 }
luxsci.com
LuxSci API v2: Mechanics 43
Change SecureSend User Password
You can do this with the User Update function, above. We provide a simple, direct method here as well.
Request Method PUT Access Required SecureSend NameSpace Management /perl/api/v2/account/[account id]/pl/namespaces/[namespace Request URL 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 }
luxsci.com
44 LuxSci API v2: Mechanics
Get SecureSend User Single Sign-On Link
Create a URL that the user can click on which will automatically log the user into the SecureSend Interface without needing to enter his/her username and password. For example, if the user has already authenticated him/herself in your system, you can use this API call to get a link that can be presented to the user so the user can then access SecureSend without needing to login again (e.g. “single sign-on”).
Notes:
1. This API call returns a URL. You can have the user click on that URL or you can redirect him/her to it. 2. This URL is valid for 15 minutes from the time of issuance. It can be used multiple times while it is in use. 3. These URLs are invalidated if the user’s password is changed. 4. These URLs will only work for someone coming from the IP address that your specified in your request for the URL 5. All logins via Single Sign-on are logged in the user’s History and are denoted as Single Sign-on logins therein
Request Method GET SecureSend NameSpace Management Access Required SecureSend Single sign-On /perl/api/v2/account/[account id]/pl/namespaces/[namespace Request URL 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.
luxsci.com
LuxSci API v2: Mechanics 45
Not that the SecureSend NameSpace specified must be associated with this Theme, or the API will return an error.
Result
This returns the URL.
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
luxsci.com
46 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 47
Access to all of these reports is very similar. They all use an HTTP GET; account-wide reports use account scope; user-specific reports are available under user scope; all reports use the same mechanism for restricting date ranges and requesting particular “pages” of results. The following section specifies the usage features common to all of these report types. The subsequent sections discuss each of the particular account scope reports available. See the “User” guide for a list of the respective user scope reports.
Report Querying and Results: Commonalities
All API queries for “Reports” are HTTP GETs with optional query strings that allow you to narrow down the scope of the request and/or select which of the many matches to actually return. The following table lists the optional query string parameters that you can use with any report request. The meaning of “date” referred to in the date restrictions will depend on what API call is being executed.
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.
luxsci.com
48 LuxSci API v2: Mechanics
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
luxsci.com
LuxSci API v2: Mechanics 49
Messages sent via WebMail /perl/api/v2/account/[account id]/report/email/webmail/sent Request Query String All standard reporting parameters, plus See Below.
Dates, for the purposes of narrowing results, refer to the date the message was sent (as defined as the date/time it was received by the API). This corresponds to the “date_sent” output field. Request Body none Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
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
luxsci.com
50 LuxSci API v2: Mechanics
• 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).
luxsci.com
LuxSci API v2: Mechanics 51
opt_out Enum Value: 0 – SecureLine Opt Out not used -1 – SecureLine Opt Out use not recorded for some reason 1 – SecureLine Opt Out secureline Enum Value: any – Match anything -1 – SecureLine usage not recorded for some reason 1 – SecureLine encryption was used 0 – SecureLine encryption was not used
If SecureLine was used, use the delivery status report to see more details.
sendmail_id String Return only the message with the specified sendmail_id. sendmail_ids String Comma-delimited list of up to 100 sendmail ids. Returns any matching messages. spam Enum Value: 0 – Message was not marked as spam by a recipient and returned in a Feed Back Loop 1 – Message was marked as spam by a recipient and returned in a Feed Back Loop
subject String Case-insensitive substring search of the message subject (in UTF-8). to String Case-insensitive substring search of all recipient email addresses. tracked_headers Boolean If true and this report is for messages sent vis SMTP, then the results will include the six additional fields (header1, header2, header3, header1_value, header2_value, header3_value) which are used to track custom email message header data. user_id Integer Restrict the report to the user with this specific User ID number.
JSON Response Body
The header columns in the response include the following:
Keyword Data Type Description date_sent DATETIME When the message was sent In GMT. Format “YYYY-MM-DD HH:MM:SS”.
luxsci.com
52 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 53
high_volume Integer Value: 0 – Message sent does not count towards a High Volume or Premium High Volume sending limit 1 – It does. n_recipients Integer Number of recipients to the message notes String Internal notes opt_out Integer Value: 0 – SecureLine Opt Out not used -1 – SecureLine Opt Out use not recorded for some reason 1 – SecureLine Opt Out secureline Integer Value: -1 – SecureLine 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
luxsci.com
54 LuxSci API v2: Mechanics
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 Description Type 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
luxsci.com
LuxSci API v2: Mechanics 55
ip String Case-insensitive substring search of the sender IP address (for SMTP reports only). header1 String See: “Report: Email Sent” header1_operator Enum See: “Report: Email Sent” header1_value String See: “Report: Email Sent” 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.
luxsci.com
56 LuxSci API v2: Mechanics
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”
luxsci.com
LuxSci API v2: Mechanics 57
last_updated DATETIME When this delivery status information was last updated. E.g. for messages in the queue, they can be retried many times and each retry can result in an update to the queue reason (state_detail) or delivery status. Message status can also be update much later after sending as hard bounces come back. n_recipients Integer Number of recipients to the message secureline Integer Value: 0 – Message to this recipient did not use SecureLine -2 – SecureLine was not used due to Opt Out being selected -1 – SecureLine 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).
luxsci.com
58 LuxSci API v2: Mechanics
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 All standard reporting parameters, plus See Below. String Dates, for the purposes of narrowing results, refer to the date the message was sent. This corresponds to the “date_sent” output field.
luxsci.com
LuxSci API v2: Mechanics 59
However, if you set the “click_date” input parameter to true, then the “click_date” field will be used for date selections. Request Body none Success Response Standard response for all reports. Data field details listed below.
Additional Query String Parameters
Keyword Data Description Type 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:
luxsci.com
60 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 61
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).
luxsci.com
62 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 63
Additional Query String Parameters
Keyword Data Description Type 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.
luxsci.com
64 LuxSci API v2: Mechanics
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”
luxsci.com
LuxSci API v2: Mechanics 65
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.
luxsci.com
66 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 67
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
luxsci.com
68 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 69
server_type_code String This is a code of the format “X-A-B.extra” that uniquely identifies the kind of server that this is. A = CPU Cores; B = GB Ram; “extra” is used for AWS servers to indetify their flavor. X is one of: • r – Rackspace Public Cloud behind hardware firewalls • a – AWS Public Cloud • e – Enterprise Class Rackspace Private Cloud • p – Physical Server • g – General / other.
Servers Status
This report allows you to retrieve specific current status of a specific server. This request will actually directly interrogate the server for some of this information; in situations where the server is overloaded or down or very slow, this API will fail.
The “server_id” parameter in the Request URL should be the numeric “server_id” returned by the “Server List” API call, above. However, it can also be the short host name. I.e., if server with host “rs999” has a server_id of “197890” … you can use either “197890” or “rs999” as the “server_id”.
Request Method GET Access Required Account: Servers - Report Request URL /perl/api/v2/account/[account id]/server/server_id Request Query String none Request Body none Success Response Server information. See below.
luxsci.com
70 LuxSci API v2: Mechanics
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.
luxsci.com
LuxSci API v2: Mechanics 71
mail_queue_unprocessed Integer Number of email messages that have been received, but which are waiting to be processed (i.e., for encryption or other activities) before being re-queued for delivery to their ultimate recipients. Note: if you have delivery rate limiting on, messages that are not being delivered due to rate limiting will show as “unprocessed”. mail_queue_trying Integer Number of email messages that are in the email queues waiting to be delivered to their ultimate recipients. This includes messages that have tried and failed to be delivered due to temporary failures or blocks. disks Array This is an array of hashes, one for each mount point on the server. The hashes for each mount point include the following keywords: • mount – the name of the mount point • size_mb – the size of the disk in MB • used_mb – the space used in MB • io_used_pct – the disk IO utilization percentage. When this is high, processes that read and write to the drive will be slower.
luxsci.com
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.