LuxSci

Authentication

authentication

In order to use any API commands, at any level, your client must first authenticate and obtain an authentication code. This authentication code can then be used to make one or more calls to API functions. our authentication "session" can also be revoked, immediately invalidating all authentication codes received for it (i.e., this is a "log out"). In order to authenticate, you will need your API Token, API Key, and your API Host name. This API request is different from authenticated request in that you do not need to send a cookie, and the way that the request is signed is different. See also [Authentication](/rest-api/mechanics.html#auth).


/auth

Parameters

Body parameters
Name Description
body

Responses

Status: 201 - Standard JSON response. No "data" keyword will be sent. See the "auth" keyword for your new authentication token.

{"auth":"66840164-1617889562-3d472a77806a340161982d8e034219034007ed9518f452f4b6f8c2ddd8b5b03a","success":1}

revokeAuthentication

Revoke your authentication session and invalidate all authorization codes received. See also [Revocation](/rest-api/mechanics.html#revoke).


/auth

Parameters

Header parameters
Name Description
Cookie*

Responses

Status: 200 - Standard JSON response. No "data" keyword will be sent.

{"success":1,"comment":"Authentication session revoked."}

Domains

createDomain

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.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/domains

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"id":"45623"}}

deleteDomain

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.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/domains/{domainName}

Parameters

Path parameters
Name Description
accountId*
String
Required
domainName*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1}

getDomainDetails

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

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/domains/{domainName}

Parameters

Path parameters
Name Description
accountId*
String
Required
domainName*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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.

{"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}}

getDomainsReport

Get information about your domains.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/domains

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - The data field of the response is an array of all domains in your account.

{"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}]}

updateDomain

Change selected domain settings. You can change one or multiple settings via one call. Settings that are omitted will not be altered.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/domains/{domainName}

Parameters

Path parameters
Name Description
accountId*
String
Required
domainName*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - none

{"auth":"OMITTED","success":1}

Email

createDkim

Create a new DKIM configuration in your account.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/dkim

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK


deleteDkim

Remove a DKIM definition from your account.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/dkim/{domainName}

Parameters

Path parameters
Name Description
accountId*
String
Required
domainName*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1}

deleteEmailAutoResponder

Delete an email auto-responder number `id` that belongs to the user.

Access control required to execute this endpoint: User Email - Auto-Responders


/perl/api/v2/user/{username}/email/ar/{id}

Parameters

Path parameters
Name Description
username*
String
Required
id*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - ""

{"auth":"OMITTED","success":1}

getDkimDetails

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.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/dkim/{domainName}

Parameters

Path parameters
Name Description
accountId*
String
Required
domainName*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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'

{"auth":"OMITTED","success":1,"data":{}}

getDkimReport

Get information about your DKIM configurations.

Access control required to execute this endpoint: Account: Domains - Manage


/perl/api/v2/account/{accountId}/dkim

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - The data field of the response is an array of all DKIM definitions in your account.


getEmailAutoResponders

Return all email auto-responders owned by this user.

Access control required to execute this endpoint: User Email - Auto-Responders


/perl/api/v2/user/{username}/email/ar

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - A successful response will return an array of objects, one for each auto-responder owned by this user.

{"auth":"OMITTED","success":1,"data":[{"signature_from":"john@sample.com","match_ what":"yahoo.com","match_type":"To domain","in_reply":0,"subject":"Respond to this!","status":"scheduled","window_start":"2015-04-01 00:00:00","signature_name":"John Sample","body":"Leave me alone!","duplicate_interval":30,"window_end":"2015-05-01 00:00:00","id":708967,"title":"Test","is_body_html":0,"signature_id":123723}]}

newEmailAutoResponder

Create a new email auto-responer.

Access control required to execute this endpoint: User Email - Auto-Responders


/perl/api/v2/user/{username}/email/ar

Parameters

Path parameters
Name Description
username*
String
Required
Body parameters
Name Description
body

Responses

Status: 200 - A successful response will return the unique ID of the created auto-responder.

{"auth":"OMITTED","success":1,"data":{"id":105789}}

retrieveSecureLineRecipientListEncryptionData

When composing an email message, you may have a list of recipients and want to know what kind of encryption, if any, would be used for each recipient when it is finally sent out with SecureLine encryption. E.g. this can be used to (a) inform the sender of what encryption will be used, and (b) to discover ahead of time if there are some recipients for which a message cannot yet be encrypted (possible, for example, if SecureLine Escrow is setup to use question and answer authentication without a default fall-back question and answer). It is good to use this method before sending an encrypted message – so you can modify your recipient list and/or add additional required encryption information before sending. Note: This is a RPC-style call and hence uses a POST method even though we are “getting data”. We are interacting with the system rather than querying a specific resource.

Access control required to execute this endpoint: User Email - Sending


/perl/api/v2/user/{username}/email/compose/secureline/recipients

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - The response body for a successful request will contain a hash in the “data” field with one keyword, “recipients”. The value of “recipients” is a list. Each list element will be another list corresponding to one of your queried recipients.

{"auth":"OMITTED","success":1,"data":{"recipients":[["ann@mail.co.cc","escrow",null,60],["kangas@luxsci.com","pgp"],["joe@gmail.com","tls"]]}}

updateEmailForwarding

This function allows you to alter the email forwarding (and denial/deletion) settings for the user.

Access control required to execute this endpoint: User Email - Forwarding


/perl/api/v2/user/{username}/email/forwarding

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - ""

{"auth":"OMITTED","success":1}

Email Aliases

createAlias

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. 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.

Access control required to execute this endpoint: Account: Email Aliases - Manage


/perl/api/v2/account/{accountId}/aliases

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"added":1}}

deleteAlias

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

Access control required to execute this endpoint: Account: Email Aliases - Manage


/perl/api/v2/account/{accountId}/aliases/{aliasAddress}

Parameters

Path parameters
Name Description
accountId*
String
Required
aliasAddress*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1}

getAliasDetails

Get information about a specific email alias.

Access control required to execute this endpoint: Account: Email Aliases - Manage


/perl/api/v2/account/{accountId}/aliases/{aliasAddress}

Parameters

Path parameters
Name Description
accountId*
String
Required
aliasAddress*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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.

{"auth":"OMITTED","success":1,"data":{"bounce":null,"dest":"other@address.com","status":"enabled","domain":"sample.com","user":"john","action":"email","type":"Alias","distribution_list_group":null,"created":"2015-03-02 07:11:33"}}

getAliasesReport

Get information about your email aliases including regular aliases user forwards, domain catchalls, and WebAide Group distribution lists.

Access control required to execute this endpoint: Account: Email Aliases - Manage


/perl/api/v2/account/{accountId}/aliases

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - The data field of the response is an array of all aliases in your account.

{"auth":"OMITTED","success":1,"data":[{"bounce":null,"dest":"other@address.com","status":"enabled","domain":"sample.com","user":"john","action":"email","type":"Alias","distribution_list_group":null,"created":"2015-03-02 07:11:33"}]}

updateAlias

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.

Access control required to execute this endpoint: Account: Email Aliases - Manage


/perl/api/v2/account/{accountId}/aliases/{aliasAddress}

Parameters

Path parameters
Name Description
accountId*
String
Required
aliasAddress*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - None

{"auth":"OMITTED","success":1}

Email Sending

createAccountSuppression

Add new email suppressions at the account level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/account/{accountId}/suppression/

Parameters

Path parameters
Name Description
accountId*
Integer
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - None

{"auth":"OMITTED","success":1,"data":{}}

createEmailTemplate

Define a new email template.

Access control required to execute this endpoint: User Email: SMTP/API Templates


/perl/api/v2/user/{username}/templates

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - Results in the “data” component of the response.

{"auth":"OMITTED","success":1,"data":{"template_id":23}}

createUserSuppression

Add new email suppressions at the user level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/user/{username}/suppression/

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - None

{"auth":"OMITTED","success":1,"data":{}}

deleteAccountSuppression

Delete a specific account-level email suppression.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/account/{accountId}/suppression/{email}

Parameters

Path parameters
Name Description
accountId*
Integer
Required
email*
String
Suppression email address to be deleted.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1,"data":{}}

deleteEmailTemplate

Delete a specific email template.

Access control required to execute this endpoint: User Email: SMTP/API Templates


/perl/api/v2/user/{username}/template/{template_id}

Parameters

Path parameters
Name Description
username*
String
Required
template_id*
String
template_id can be either the unique numerical template_id or the text code_word
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1,"data":{}}

deleteUserSuppression

Delete a specific user-level email suppression.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/user/{username}/suppression/{email}

Parameters

Path parameters
Name Description
username*
String
Required
email*
String
Suppression email address to be deleted.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - none

{"auth":"OMITTED","success":1,"data":{}}

getAccountSuppression

Retrieve a specific email suppression at the account level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/account/{accountId}/suppression/{email}

Parameters

Path parameters
Name Description
accountId*
Integer
Required
email*
String
Suppression email address to be retrieved. You are returning all suppression entries that contain the string 'email'. Note that even if you specify a full email address for 'email,' you can get multiple matches.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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 does not 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.

{"auth":"OMITTED","success":1,"data":["email@domain.com,0,101010,0,0"]}

getAccountSuppressionList

Retrieve all email suppressions at the account level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/account/{accountId}/suppression/

Parameters

Path parameters
Name Description
accountId*
Integer
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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 does not 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.

{"auth":"OMITTED","success":1,"data":["email@domain.com,0,101010,0,0"]}

getDomainSmtpTlsCapability

This function checks if a specific domain name supports “good” SMTP TLS for email delivery to its users. This means: - All MX records are working - SMTP TLS is supported by all MX records - TLS support includes TLS v1.0+ and strong (NIST 800-52 recommended) ciphers like AES256. For more background, see: - [About SMTP TLS](https://luxsci.com/blog/smtp-tls-all-about-secure-email-delivery-over-tls.html) - [What Level of SSL/TLS is needed for HIPAA?](https://luxsci.com/blog/level-ssl-tls-required-hipaa.html)

Access control required to execute this endpoint: User Email - Sending


/perl/api/v2/user/{username}/email/compose/secureline/tls/{domain}

Parameters

Path parameters
Name Description
username*
String
Required
domain*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - The response body for a successful request will have a keywords and data in the “data” in the JSON response.

{"auth":"OMITTED","success":1,"data":{"domain":"gmail.com","tls":1}}

getEmailTemplate

The call returns the specific details around a specific Email Template.

Access control required to execute this endpoint: User Email: SMTP/API Templates


/perl/api/v2/user/{username}/template/{template_id}

Parameters

Path parameters
Name Description
username*
String
Required
template_id*
String
can either be the numerical unique ID of the template, or the textual “code_word”
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - Results in the “data” component of the response.

{"auth":"OMITTED","success":1,"data":{"code_word":"campaign1","template_id":23,"subject":"Campaign example subject","sl_opt_out":0,"sl_opt_in":0,"modified":"2020-06-15 20:43:57","created":"2020-06-15 20:43:57","body_text":"Test message body.","format":"both","sl_no_tls":1,"title":"Example template","body_html":"<p>Test message body</p>","notes":"My notes"}}

getEmailTemplateList

This function returns a list of all templates defined in your account.

Access control required to execute this endpoint: User Email: SMTP/API Templates


/perl/api/v2/user/{username}/templates

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - Results in the “data” component of the response. The data component is a list of associated arrays. Each associate array corresponds to a single template

{"auth":"OMITTED","success":1,"data":[{"code_word":"campaign1","template_id":23,"title":"Example template","notes":"My notes"}]}

getUserSuppression

Retrieve a specific email suppression at the user level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/user/{username}/suppression/{email}

Parameters

Path parameters
Name Description
username*
String
Required
email*
String
Suppression email address to be retrieved. You are returning all suppression entries that contain the string 'email'. Note that even if you specify a full email address for 'email,' you can get multiple matches.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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, date_time_created, notes]. "email" is the email address suppressed. "expires" is the number of days until it expires, or zero if it does not 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. "date_time_created" is in GMT.

{"auth":"OMITTED","success":1,"data":["email@domain.com,0,101010,0,0"]}

getUserSuppressionList

Retrieve all email suppressions at the user level.

Access control required to execute this endpoint: User Email: Suppression


/perl/api/v2/user/{username}/suppression/

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - 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, date_time_created, notes]. "email" is the email address suppressed. "expires" is the number of days until it expires, or zero if it does not 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. "date_time_created" is in GMT.

{"auth":"OMITTED","success":1,"data":["email@domain.com,0,101010,0,0"]}

sendEmail

This API call is a generic outbound email sending interface that is designed to enable efficient large-scale email sending through your account’s email servers. It is ideal for Secure High Volume email sending. See - [sendEmail vs sendSecureEmailOrSecureText endpoints](/rest-api/sending-email.html) for sending email via the LuxSci API. This API function is used to send message(s) through your account’s SMTP server(s). You can think of it as an API-based proxy to SMTP, used for cases where direct use of SMTP is not an option. Generally speaking, direct use of SMTP is overall faster and more efficient; however, the API does include some things that you cannot get through direct SMTP connections. For example, the API includes support for failover, load-balanced SMTP servers; this can be done with direct SMTP only if you have a load balancer in front of your servers. You can also hand off messages to LuxSci (into the outbound queues) faster through the API than you can through direct SMTP. As this is a proxy for SMTP, the majority of the email message processing actually happens on the SMTP servers themselves (just like it would if you had actually used direct SMTP to send the message). The API call accepts the message, vets your ability to send the message, queues the message, and the moves it to the appropriate SMTP servers for delivery. This API process is designed to be very safe and efficient and works well for customers with very large SMTP sending limits (e.g., millions of messages per month). This API function allows you to optionally include attachments. If you wish to include attachments, you must format your request as a `multipart/form-data` request as discussed in the [API Mechanics Guide](/rest-api/mechanics.html). If the API call “fails” … it may be because more information is needed to encrypt the message to your recipients, if the request is malformed, or if your sending has exceeded some limit. Here are some limits to be aware of 1. The sending user must have an SMTP license. 2. The sending user must have a SecureLine license to use SecureLine-specific parameters. 3. You have to send to at least 1 recipient, but no more than 100 recipients per message. This limit can be increased on dedicated servers. 4. Your API call can contain 1 to 1000 messages. This limit can be increased on dedicated servers. 5. The total number of recipients across all messages in your API call cannot exceed 1000. This limit can be increased on dedicated servers. 6. The messages sent by a user through this API call count towards the users’ daily and monthly SMTP sending (just as if the user had actually used direct SMTP to send) totals. So, messages will be rejected if a user exceeds any of these limits. Please contact support if you need to upgrade these limits. 7. While SecureLine-encrypted emails sending is supported through this API call, SecureText sending is not. 8. If there are restrictions configured in the Domain Administration control panel on to whom the sending user can send messages, these restrictions also apply to messages sent through the API. 9. The total size of the message subject, body, and all attachments (raw size) must be less than or equal to 66% the sender’s SMTP message sending size limit. This limit can be affected by use of Email Archival, custom domain-level size limits, and general global limits. The current value of this limit can be found in the “Maximum Message Size Limit” for the sender’s domain in your domain administration settings area. 66% is used because, when the attachments are encoded into an actual email message, the size can bloat to 140-150% of the raw size; the SMTP message size limit looks at the size of the encoded messages passing through your SMTP servers. Note that once messages sent via this API arrive on your SMTP server for processing and delivery, those messages are subject to any server delivery rate limiting settings currently enabled on the SMTP server. For example, if your SMTP server is “warming up” its IP address by slowly increasing its outbound email delivery rate, messages sent by the API through that server may be delayed by that warmup rate limit. **Maximizing your sending rate:** To deposit email messages in the outbound queues as fast as possible using the API, we recommend 1. Send as many messages as you can in each API call. This “pipelining” greatly reduces the number of API calls you need to execute and greatly speeds up processing of your messages. 2. When sending same attachments in multiple messages, use the API’s feature for including the attachment once and referencing it in each of the actual messages. This will greatly speed up the uploading/posting of your message information to the API server. 3. Keep the messages as small as possible. 4. If appropriate for your use case, send fewer messages. Have more recipients per message (using the `bcc` field if needed). 5. Ask support about dedicated API servers. If all of the server resources are dedicated to your account, your throughput can be higher. You can also use multiple load-balanced dedicated API sending servers to scale your throughput capacity. Under ideal conditions, you should be able to deposit outbound email messages in the API queues much faster that your email servers can actually deliver those messages to the actual recipients (unless you have a number of powerful dedicated email servers). That is OK, your email servers will just process and delivery them as fast as they can. The actual rate of message delivery to the recipients will be a function of how many email servers you have, what their specs are, how busy they are, and many other factors involved in SMTP email delivery – such as the recipients’ DNS response time, the recipient’s inbound email server speeds, etc.

Access control required to execute this endpoint: User Email: Sending


/perl/api/v2/user/{username}/email/send

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body
Form parameters
Name Description
json
userusernameemailsend_json
files
array[byte[]] (binary)

Responses

Status: 200 - The response body for a successful request will contain a hash in the “data” field. The value of this data field is an array which lists the unique sendmail_id codes for each of the messages sent. These codes can be used in the reporting API functions to look up delivery status and other message details. If multiple messages were sent in a single API call, multiple sendmail_id codes will be returned and the order of the codes in the array will exactly match the order of the messages in the API call.

{"auth":"OMITTED","success":1,"data":["L3CJvSVVa74574"]}

sendSecureEmailOrSecureText

Send Secure Email and/or SecureText messages through your WebMail servers. This API endpoint is deprecated; use the sendEmail endpoint instead.. See [sendEmail vs sendSecureEmailOrSecureText endpoints](/rest-api/sending-email.html) for sending email via the LuxSci API.

Access control required to execute this endpoint: User Email: Sending


/perl/api/v2/user/{username}/email/compose/secureline/send

Parameters

Path parameters
Name Description
username*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - ""

{"auth":"OMITTED","success":1}

updateEmailTemplate

This template update call will update/replace ALL FIELDS. So, include all fields, as omitted fields will be treated as if you are updating them with empty or false values. This is effectively just like deleting the old template with this `template_id` and replacing it with the new data.

Access control required to execute this endpoint: User Email: SMTP/API Templates


/perl/api/v2/user/{username}/template/{template_id}

Parameters

Path parameters
Name Description
username*
String
Required
template_id*
String
template_id can be either the unique numerical template_id or the text code_word
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - None

{"auth":"OMITTED","success":1,"data":{}}

Marketing

addMarketingCampaign

Create a new email broadcast campaign.

Access control required to execute this endpoint: Marketing - Campaign Management


/perl/api/v2/account/{accountId}/marketing/addCampaign

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"subject":"LUXSCI TEST CAMPAIGN","name":"LUXSCI TEST CAMPAIGN","content_text":"Hello World!","created_at":"2020-06-10 20:22:18","group_id":24,"updated_at":"2020-06-10 20:22:18","content_html":"<h1>Hello World!</h1>","id":8,"user_id":3}}

addMarketingContact

Add New Contact.

Access control required to execute this endpoint: Marketing - Contact Management


/perl/api/v2/account/{accountId}/marketing/addContact

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"is_spamed":0,"import_id":null,"additional_fields_data":{"customer_id_custom_field":999},"is_verified":0,"email":"support@luxsci.com","created_at":"2020-06-10 18:38:26","id":19,"list_id":28,"never_sent":null,"bounced":"no_process","image":null,"is_unsubscribed":0,"is_active":1,"format":"html","updated_at":"2020-06-10 18:38:26","is_confirmed":1,"user_id":3}}

addMarketingList

Add New Contact List.

Access control required to execute this endpoint: Marketing - List Management


/perl/api/v2/account/{accountId}/marketing/addList

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - Includes ID and fields matching those sent in the request or which you would normally get from contact list queries. Ses the getLists.

{"auth":"OMITTED","success":1,"data":{"custom_fields":[],"bounce_email_id":1,"import_cancel":0,"copying":0,"reply_email":"support+reply@luxsci.com","name":"TEST_LIST_1591809030","owner_email":"support@secured-message.com","created_at":"2020-06-10 17:10:30","group_id":15,"updated_at":"2020-06-10 17:10:30","id":20,"user_id":3,"owner_name":"LUXAPITEST"}}

addNewMarketingSuppression

Add New Suppression.

Access control required to execute this endpoint: Marketing - Suppression


/perl/api/v2/account/{accountId}/marketing/suppress

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - The response is an associative array

{"auth":"OMITTED","success":1,"data":{"email":"customer@domain.com","label":"suppression via api","created_at":"2020-06-10 20:22:18","is_suppressed":1,"updated_at":"2020-06-10 20:22:18","list_id":7,"id":8,"user_id":3}}

deleteMarketingCampaign

Delete a Campaign.

Access control required to execute this endpoint: Marketing - Campaign Management


/perl/api/v2/account/{accountId}/marketing/deleteCampaign/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
Integer
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1}

deleteMarketingContactById

Delete Contact By ID.

Access control required to execute this endpoint: Marketing - Contact Management


/perl/api/v2/account/{accountId}/marketing/deleteContact/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
Integer
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - ""

{"auth":"OMITTED","success":1}

deleteMarketingList

Note: deleting a contact list will delete any contacts in that list.

Access control required to execute this endpoint: Marketing - List Management


/perl/api/v2/account/{accountId}/marketing/deleteList/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
String
List Id.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1}

deleteMarketingListGroup

Note: deleting a contact list group will NOT delete any contact lists in that group; they will merely become unassociated with any group.

Access control required to execute this endpoint: Marketing - List Management


/perl/api/v2/account/{accountId}/deleteListGroup/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
String
List group Id.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1}

deleteMarketingSuppression

Delete Suppression.

Access control required to execute this endpoint: Marketing - Suppression


/perl/api/v2/account/{accountId}/marketing/deleteSuppressed/{type}

Parameters

Path parameters
Name Description
accountId*
String
Required
type*
String
email, domain, ip Select type of suppression
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
id
Integer
id of the suppressed entry
reference
String
Select suppressed records according to this reference you want to delete

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1}

getMarketingCampaignBouncedStatistics

Get Campaign bounced statistics.

Access control required to execute this endpoint: Marketing - Statistics


/perl/api/v2/account/{accountId}/marketing/getCampaignStatsBounced/{schedule_id}

Parameters

Path parameters
Name Description
accountId*
String
Required
schedule_id*
Integer
Schedule id of schedule to get bounced stats
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
limit_start
Integer
Starting row of result. Default: 0
limit_count
Integer
Number of records to get. Default: 25

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"id":5,"created_at":"2020-07-19 11:37:20","email":"edward@yahoo.com","type":"hard","code":" (344)","reason":"421 4.7.0 [TSS04] Messages from 50.31.49.42 temporarily deferred due to user complaints -4.16.55.1; see https://help.yahoo.com/kb/postmaster/SLN3434.html","smtp_id":25,"message_id":"<312a04168e5cd4fb3672889f0ded84f58@domain.com>","smtp":"luxsci","subscribers_id":72}]}

getMarketingCampaignClickedStatistics

Get Campaign email link clicked statistics.

Access control required to execute this endpoint: Marketing - Statistics


/perl/api/v2/account/{accountId}/marketing/getCampaignStatsClicked/{schedule_id}

Parameters

Path parameters
Name Description
accountId*
String
Required
schedule_id*
Integer
Schedule id of schedule to get clicked stats
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
limit_start
Integer
Starting row of result. Default: 0
limit_count
Integer
Number of records to get. Default: 25

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"id":15,"broadcast_id":18,"scheduled_id":111,"contact_id":3820183,"sd_id":null,"sn_id":null,"campaign_schedule_logs_id":498,"link_id":111,"link":"https://www.youtube.com/watch?v=ECvGtQjhjy0&list=RDECvGtQjhjy0&start_radio=1","ip_address":"39.34.209.252","ip_country":"Pakistan","ip_region":"Punjab","ip_city":"Mianwali","ip_zip":"42201","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.121 Safari/537.36","created_at":"2020-10-02 13:19:49","updated_at":"2020-10-02 13:19:49","subscriber_email":"adam@gmail.com","link_url":"https://www.youtube.com/watch?v=ECvGtQjhjy0&list=RDECvGtQjhjy0&start_radio=1","is_unsubscribed":0,"subscribers_id":3820183}]}

getMarketingCampaignOpenedStatistics

Get Campaign email opened statistics.

Access control required to execute this endpoint: Marketing - Statistics


/perl/api/v2/account/{accountId}/marketing/getCampaignStatsOpened/{schedule_id}

Parameters

Path parameters
Name Description
accountId*
String
Required
schedule_id*
Integer
Schedule id of schedule to get open stats
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
limit_start
Integer
Starting row of result. Default: 0
limit_count
Integer
Number of records to get. Default: 25

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"id":23,"broadcast_id":18,"scheduled_id":111,"contact_id":3820183,"sd_id":null,"sn_id":null,"campaign_schedule_logs_id":498,"is_clicked":1,"ip_address":"39.34.209.252","ip_country":"Pakistan","ip_region":"Punjab","ip_city":"Mianwali","ip_zip":"42201","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.121 Safari/537.36","user_id":null,"created_at":"2020-10-02 13:19:49","updated_at":"2020-10-02 13:19:49","smtp":"Admin Zone1","email":"johny@gmail.com","subscribers_id":3820183}]}

getMarketingCampaignStatisticsSummary

Get Campaign statistics summary.

Access control required to execute this endpoint: Marketing - Statistics


/perl/api/v2/account/{accountId}/marketing/getCampaignStatsSummary/{schedule_id}

Parameters

Path parameters
Name Description
accountId*
String
Required
schedule_id*
String
Schedule id of schedule to get its statatistics summary.
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"campaign_name":"testing","sent_by":2,"contact_list":"Active List","campaign_list":"Testing Dynamic Tag","sending_node":"Admin Zone1","time_start":"Nov 03, 2020 05:58:52 PM","time_finished":"Nov 03, 2020 06:03:13 PM","status":"complete","total_contacts":4,"sent":4,"opened":"25 %","clicked":"0 %","ctr":"0 %","bounced":"0 %","unsubscribed":"25 %","threads":5,"track_opens":"Yes","track_clicks":"Yes","unsubscribe_link":"Yes","hourly_speed":"N/A","scheduled_by":"admin@dev1.com on Nov 03, 2020 05:58:52 PM"}}

getMarketingCampaignUnsubscribedStatistics

Get Campaign email unsubscribed statistics.

Access control required to execute this endpoint: Marketing - Statistics


/perl/api/v2/account/{accountId}/marketing/getCampaignStatsUnsubscribed/{schedule_id}

Parameters

Path parameters
Name Description
accountId*
String
Required
schedule_id*
Integer
Schedule id of schedule to get unsubscribe stats
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
limit_start
Integer
Starting row of result. Default: 0
limit_count
Integer
Number of records to get. Default: 25

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"subscribers_id":3820181,"email":"david@yahoo.com","updated_at":"2020-11-03 13:10:58","id":29,"broadcast_id":19,"scheduled_id":195,"contact_id":3820181,"sd_id":null,"sn_id":null,"campaign_schedule_logs_id":944,"is_clicked":0,"ip_address":"39.34.221.158","ip_country":"Pakistan","ip_region":"Punjab","ip_city":"Jauharabad","ip_zip":"29211","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36","user_id":2,"created_at":"2020-11-03 13:10:58"}]}

getMarketingCampaigns

This call allows you to retrieve details on your campaigns.

Access control required to execute this endpoint: Marketing - Campaign Management


/perl/api/v2/account/{accountId}/marketing/getCampaigns

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
id*
Integer
Use if you want to restrict details to specific Campaign id. If left blank, all your campaigns’ details will be returned.
Required
group_id*
Integer
Group id of the campaigns you want to get.
Required
limit_start*
Integer
Starting row of result. Default: 0
Required
limit_count*
Integer
Number of records to get. Default: 25
Required

Responses

Status: 200 - The response is an array of associated arrays

{"auth":"OMITTED","success":1,"data":{"subject":"LUXSCI TEST CAMPAIGN","name":"LUXSCI TEST CAMPAIGN","content_text":"Hello World!","created_at":"2020-06-10 20:22:18","group_id":24,"updated_at":"2020-06-10 20:22:18","content_html":"<h1>Hello World!</h1>","id":8,"user_id":3}}

getMarketingContactById

This function allows you to get the details for specific contact using his/her contact ID.

Access control required to execute this endpoint: Marketing - Contact Management


/perl/api/v2/account/{accountId}/marketing/getContact/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
Integer
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
full_details
Integer
If specified and set to 1, add contact details will be returned, including the values of all additional fields.

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"is_spamed":0,"bounced":"no_process","is_verified":0,"email":"support@luxsci.com","is_unsubscribed":0,"created_at":"2020-06-10 18:59:27","format":"html","is_active":1,"updated_at":"2020-06-10 18:59:27","user_id":3,"id":20,"list_id":29,"is_confirmed":1}]}

getMarketingContacts

This call permits you to get your contacts’ data from the system by specific list or in aggregate. None of the request body parameters are required, and if you leave them blank, the call will return all contacts’ data from all your lists.

Access control required to execute this endpoint: Marketing - Contact Management


/perl/api/v2/account/{accountId}/marketing/getContacts

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
full_details
Integer
If specified and set to 1, add contact details will be returned, including the values of all additional fields.
list_id*
Integer
Contact list id for the contacts you want to get.
Required
limit_start*
Integer
Starting row of result. Default: 0
Required
limit_count*
Integer
Number of records to get. Default: 25
Required

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":[{"is_spamed":0,"bounced":"no_process","is_verified":0,"email":"support@luxsci.com","is_unsubscribed":0,"created_at":"2020-06-10 18:59:27","format":"html","is_active":1,"updated_at":"2020-06-10 18:59:27","user_id":3,"id":20,"list_id":29,"is_confirmed":1}]}

getMarketingLists

Return details about one or more specific Contact List(s). If you omit all parameters, all lists should be returned.

Access control required to execute this endpoint: Marketing - List Management


/perl/api/v2/account/{accountId}/marketing/getLists

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
list_id
Integer
List id for the specific contact list you want details for.
group_id
Integer
Group id for all getting lists in a specific group

Responses

Status: 200 - This will return a list of associated arrays each containing standard list details.

{"auth":"OMITTED","success":1,"data":{"custom_fields":[],"bounce_email_id":1,"import_cancel":0,"copying":0,"reply_email":"support+reply@luxsci.com","name":"TEST_LIST_1591809030","owner_email":"support@secured-message.com","created_at":"2020-06-10 17:10:30","group_id":15,"updated_at":"2020-06-10 17:10:30","id":20,"user_id":3,"owner_name":"LUXAPITEST"}}

getMarketingSuppressions

Get Suppressions.

Access control required to execute this endpoint: Marketing - Suppression


/perl/api/v2/account/{accountId}/marketing/getSuppressed

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Query parameters
Name Description
type*
String
email, domain, ip Select type of suppression list you want to get
Required
id
Integer
id of the suppressed entry
reference
String
Get suppressed records according to this reference
limit_start
Integer
Starting row of result. Default: 0
limit_count
Integer
Number of records to get. Default: 25

Responses

Status: 200 - The response is an array of associative arrays.

{"auth":"OMITTED","success":1,"data":[{"email":"customer@domain.com","label":"suppression via api","created_at":"2020-06-10 20:22:18","is_suppressed":1,"updated_at":"2020-06-10 20:22:18","list_id":7,"id":8,"user_id":3},{"email":"customer2@domain.com","label":"suppression via api","created_at":"2020-06-10 20:22:18","is_suppressed":1,"updated_at":"2020-06-10 20:22:18","list_id":7,"id":9,"user_id":3}]}

markContactAsUnsubscribed

Changes a contact’s status to “unsubscribed.” This is more efficient than calling updateContact to make this change.

Access control required to execute this endpoint: Marketing - Contact Management


/perl/api/v2/account/{accountId}/markAsUnsubscribed/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
String
Required
Header parameters
Name Description
Cookie

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1}

scheduleMarketingCampaign

Schedule Campaign.

Access control required to execute this endpoint: Marketing - Scheduling


/perl/api/v2/account/{accountId}/marketing/campaignSchedule

Parameters

Path parameters
Name Description
accountId*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK

{"auth":"OMITTED","success":1,"data":{"campaign_type":"regular","threads":1,"send_datetime":"2020-10-21 13:23:45","list_ids":"90","from_attributes":"{\"unsubscribe_email\":null,\"unsubscribe_link\":null,\"unsubscribe_by_email\":null,\"from_name_list\":\"N\",\"from_name_smtp\":\"Y\",\"from_name\":null,\"bounce_email\":null,\"reply_email\":null,\"from_email\":null}","name":"james@anydomain.com","unsub_show":0,"track_opens":0,"track_clicks":0,"track_duplicate":0,"unsubscribe_header":0,"smtp_ids":"26","current_smtp":26,"smtp_sequence":"loop","sending_pattern":"random","campaign_ids":"18","send_campaign":"now","user_id":2,"sender_option":"smtp","hourly_speed":null,"masked_domain":null,"notification_email":null,"type":"subscriber","thread_settings":1,"updated_at":"2020-10-21 13:23:45","created_at":"2020-10-21 13:23:45","id":193}}

updateMarketingCampaign

Update a Campaign.

Access control required to execute this endpoint: Marketing - Campaign Management


/perl/api/v2/account/{accountId}/marketing/updateCampaign/{id}

Parameters

Path parameters
Name Description
accountId*
String
Required
id*
String
Required
Header parameters
Name Description
Cookie
Body parameters
Name Description
body

Responses

Status: 200 - OK