LuxSci API: Report Responses

Report Response Data

All API "Reports" return a JSON response body that contains a "header" which describes all of the columns of data returned. See Reporting Basics for an overview of API Reporting.

The sections, below, provide definitions for the column headings that may appear in most types of API reports (and also in Automated Reports, which push API-generated reporting data directly to customers via WebHooks, email, and other means).

Report Response Data Definitions

Asynchronous Job

Asynchronous Job Status

Responses for endpoints: getAccountJobs & getUserJobs

Keyword	Date Type	Description
`job_id`	Integer	Unique numerical ID number for the background job.
`filename`	String	The name of the file that will be uploaded to your destination when the job successfully completes.
`created`	DATETIME	When the report request was submitted.
`updated`	DATETIME	When the job status was last updated.
`completed`	DATETIME	When the job successfully completed (i.e., when the `status` changed to `complete`).
`status`	String	The overall status of the job. The possible values are: `submitted` - Request just made `preparing` - Determining the number of rows that will be produced `running` - Querying and exporting rows `uploading` - Uploading the results file to `destination_hostname` `complete` - Successfully done `failed` - Apparently failed
`status_detail`	String	For `status` of `failed`, this is a textual description of the reason for failure.
`expected_rows`	Integer	Once the `status` is `running`, this contains the number of rows that are expected to be generated by the report. This is controlled by the number of items matching the query parameters, the `start_row`, and the value of `matches`.
`completed_rows`	Integer	Once the `status` is `running`, this contains the number of rows that have been exported to the CSV results file. For large result sets, this, combined with `expected_rows`, can be used to understand the percentage completion of the request.
`uid`	Integer	Numerical user ID of the user who submitted this request. If this request was submitted at the API account level, this value will be zero.
`current_jobs`	Integer	The number of currently running asynchronous report requests for your account as a whole, including this one which you just submitted. In combination with `max_jobs`, this tells you how many more jobs you can submit before being required to wait for already-submitted jobs to first complete.
`max_jobs`	Integer	The maximum number of concurrently running asynchronous report requests permitted for your account as a whole. An asynchronous report request that would create more than this number of concurrent processes will be rejected.

User Creation Detail Reports

User Creation Detail

Responses for endpoint: getUserReport2

Keyword	Date Type	Description
`user_id`	Integer	Unique ID for this user.
`domain_id`	Integer	Unique ID for the domain the user is in (based on the user's login).
`login`	String	The user's login email address.
`created`	DATETIME	When the user was created
`modified`	DATETIME	When the user was last modified
`name`	String	Name of the user, e.g. "John Sample".

User Creation Summary Reports

User Creation Summary

Responses for endpoint: getUserSummaryReport

Keyword	Date Type	Description
`delta_users`	Integer	Number of new users created in the specified date interval.
`total_users`	Integer	Total number of active and disabled users in the account. This is independent of any specified time interval.
`user_limit`	Integer	Total number of allowed users permitted in this account before an account upgrade is needed.
`pct_users`	Float	Percentage of the allowed users now in use. This is `total_users / user_limit` and is a value between 0 and 1.
`report_date`	DATETIME	When this summary report was generated (in GMT).

Secure Marketing v3

Lists Report

Responses for endpoint: getLists

Keyword	Date Type	Description
`list_id`	Integer	Unique ID for this List
`owner_id`	Integer	Unique ID for user that owns this List
`created`	DATETIME	When the List was created.
`modified`	DATETIME	When the List was modified.
`name`	String	Name of the List
`from_email`	String	From email address for email messages sent to this List.
`from_name`	String	From name for email messages sent to this List.
`reply_email`	String	Reply-To email address for email messages sent to this List.
`n_subscribers`	Integer	Number of Contacts in this list
`list_group_id`	Integer	Unique ID of the List Group to which this List belongs. The value is "0" if it does not belong to a List Group.

Contacts Report

Responses for endpoint: getContacts

Keyword	Date Type	Description
`contact_id`	Integer	Unique ID for the Contact
`list_id`	Integer	Unique ID for the List to which the Contact belongs
`owner_id`	Integer	Unique ID for user that owns this Contact
`created`	DATETIME	When the Contact was created.
`modified`	DATETIME	When the Contact was modified.
`email`	String	Email address of this Contact
`domain`	String	Domain name part of the email address of this Contact
`is_active`	Integer	1 if the Contact is active; 0 otherwise.
additional fields	String	If a "detail" report is requested, then there will be additional columns for each of the relevant custom fields. The column name will be the "code word" for the custom field.

Email Sending Detail Reports

Email Delivery Status

Responses for endpoints: getEmailSMTPDeliveryStatusReportUser, getEmailSMTPDeliveryStatusReportAccount, getEmailWebMailDeliveryStatusReportUser & getEmailWebMailDeliveryStatusReportAccount

Keyword	Date Type	Description
`date_sent`	DATETIME	When the message was sent.
`from`	String	The From email address
`from_ip`	String	IP Address of the sending program (SMTP reports only). This can be just `MobileSync` if this email 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. E.g., if you configured your account to capture the value of the header `X-My-Header` and are 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-myheader` 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
`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 updated much later after sending as hard bounces come back, opens and clicks occur, or a recipient unsubscribes.
`n_recipients`	Integer	Number of recipients to the message
`secureline`	Enum	Values: `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`	Enum	Values: `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 that was returned in a Feed Back Loop
`Opens`	Integer	Values: `-1`: Open tracking is not enabled for this message. `0`: Open tracking enabled and message not opened. `Greater than 0`: Open tracking enabled and message opened this many times.
`Clicks`	Integer	Values: `-1`: URL Click tracking not enabled for this message. `0`: Click tracking enabled but no URLs in the message have yet been clicked on. `Greater than 0`: Click tracking enabled and this many times URLs have been clicked on.
`Unsubscribed`	Enum	Values: `0`: Recipient did not unsubscribe based on this email message. `1`: The recipient did unsubscribe based on this email message.
`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 successfully accepted by the recipient's server, 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")
`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`	Enum	Values: `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. I.e., ciphers, etc.
`to`	String	Single recipient email address for this delivery.
`user`	String	Login email address of the user who sent the message
`user_id`	Integer	User ID of the user who sent the message
`template_id`	Integer	The ID number of the template used in the sending of this email message. The value is `0` if no template was used.

Sent Email

Responses for endpoints: getEmailSMTPSentReportUser, getEmailSMTPSentReportAccount, getEmailWebMailSentReportUser & getEmailWebMailSentReportAccount

Keyword	Date Type	Description
`date_sent`	DATETIME	When the message was sent.
`from`	String	The From email address
`from_ip`	String	IP Address of the sending program (SMTP reports only). This can have the value `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. E.g., if you configured your account to capture the value of the header `X-My-Header` and are 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-myheader` 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
`high_volume`	Integer	Values: `0`: Message sent does not count as a High Volume or Secure High Volume message. `1`: It does.
`n_recipients`	Integer	Number of recipients to the message
`notes`	String	Internal notes
`opt_out`	Enum	Values: `0`: SecureLine Opt Out not used `-1`: SecureLine Opt Out use not recorded for some reason `1`: SecureLine Opt Out
`secureline`	Integer	Number of recipients to the message
`sendmail_id`	String	Unique sendmail_id of this message; useful for tracking purposes.
`size_bytes`	Integer	Size of the message in bytes.
`spam`	Enum	Values: `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 that action was returned in a Feed Back Loop
`template_id`	Integer	The ID number of the template used in the sending of this email message. The value is `0` if no template was used.
`to`	String	Comma-delimited list of recipient email address(es).
`used_tls`	Enum	Values: (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 email address of the user who sent this message
`user_id`	Integer	User ID of the user who sent the message

Email URL Clicks

Responses for endpoints: getEmailSMTPClickReportUser, getEmailSMTPClickReportAccount, getEmailWebMailClickReportUser & getEmailWebMailClickReportAccount

Keyword	Date Type	Description
`date_sent`	DATETIME	When the message was sent.
`from`	String	From email address
`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. E.g., if you configured your account to capture the value of the header `X-My-Header` and are 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-myheader` 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
`clicker_ip`	String	IP Address of the person/entity who clicked on the URL at the time of clicking.
`click_date`	DATETIME	The date and time the URL was clicked.
`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 successfully accepted by the recipient's server, 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")
`template_id`	Integer	The ID number of the template used in the sending of this email message. The value is `0` if no template was used.
`to`	String	Single recipient email address for this message.
`url`	String	The web site address (URL) that was opened.
`user`	String	Login email address of the user who sent the message
`user_id`	Integer	User ID of the user who sent the message

Email Opens

Responses for endpoints: getEmailSMTPOpenReportUser, getEmailSMTPOpenReportAccount, getEmailWebMailOpenReportUser & getEmailWebMailOpenReportAccount

Keyword	Date Type	Description
`date_sent`	DATETIME	When the message was sent.
`from`	String	From email address
`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. E.g., if you configured your account to capture the value of the header `X-My-Header` and are 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-myheader` 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
`opener_ip`	String	IP Address of the opening person/entity at the time of opening.
`open_date`	DATETIME	The date and time the message was opened.
`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 successfully accepted by the recipient's server, 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")
`template_id`	Integer	The ID number of the template used in the sending of this email message. The value is `0` if no template was used.
`to`	String	Single recipient email address for this message.
`user`	String	Login email address of the user who sent the message
`user_id`	Integer	User ID of the user who sent the message

Email SMTP Complaint Feedback Loop

Responses for endpoints: getEmailFeedBackLoopsReportUser & getEmailFeedBackLoopsReportAccount

Keyword	Date 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.
`message_type`	String	Description of how the message was sent. I.e., what sending method.
`sendmail_id`	String	Unique sendmail_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 email address of the user who sent the message
`user_id`	Integer	User ID of the user who sent the message

Email Suppressions

Responses for endpoints: getUserSuppressionReport & getAccountSuppressionReport

Keyword	Date Type	Description
`account_id`	Integer	Account ID of this customer's account.
`added`	DATETIME	When this suppression was added.
`domain_id`	Integer	Domain ID of the domain that owns this suppression if it is a domain-level or user-level suppression. `0` for account-level suppressions.
`email`	String	The email address suppressed or unsubscribed.
`expires`	Integer	The number of days until this suppression expires. `0` if it does not expire.
`note`	String	A description of how this suppression originated.
`sendmail_id`	String	For suppressions that originated from unsubscriptions from a specific sent email message, this is the `sendmail_id` of that message. This code can be used for cross-referencing and tracking.
`user_id`	Integer	User ID of the user who owns this suppression if it is a user-level suppression. `0` otherwise.

Email Sending Summary Reports

Email Delivery Status Summary

Responses for endpoints: getEmailSMTPDeliveryStatusSummaryReportUser & getEmailSMTPDeliveryStatusSummaryReportAccount

Keyword	Date Type	Description
`recipients`	Integer	Total number of message (recipients).
`queued`	Integer	Total number of messages currently in queue
`delivered`	Integer	Total number of messages successfully delivered
`hard_failed`	Integer	Total number of messages that failed to be delivered with a "hard failure" status.
`soft_failed`	Integer	Total number of messages that failed to be delivered with a "soft failure" status.
`failed`	Integer	`hard_failed` + `soft_failed`
`opened`	Integer	Number of messages that were opened at least 1 time.
`clicked`	Integer	Number of messages that were at least one URL was clicked on.
`unsubscribed`	Integer	Number of messages that were the unsubscribe link was used.
`secureline`	Integer	Number of messages that were encrypted using SecureLine (using any form of email encryption).
`secureline_escrow`	Integer	Number of messages that were encrypted using SecureLine Escrow.
`secureline_tls`	Integer	Number of messages that were encrypted using SecureLine TLS.
`pct_queued`	Float	`queued` / `recipients` — (value between 0 and 1).
`pct_delivered`	Float	`delivered` / `recipients` — (value between 0 and 1).
`pct_hard_failed`	Float	`hard_failed` / `recipients` — (value between 0 and 1).
`pct_soft_failed`	Float	`soft_failed` / `recipients` — (value between 0 and 1).
`pct_failed`	Float	`failed` / `recipients` — (value between 0 and 1).
`pct_opened`	Float	`opened` / `recipients` — (value between 0 and 1).
`pct_clicked`	Float	`clicked` / `recipients` — (value between 0 and 1).
`pct_unsubscribed`	Float	`unsubscribed` / `recipients` — (value between 0 and 1).
`pct_secureline`	Float	`secureline` / `recipients` — (value between 0 and 1).
`pct_secureline_escrow`	Float	`secureline_escrow` / `recipients` — (value between 0 and 1).
`pct_secureline_tls`	Float	`secureline_tls` / `recipients` — (value between 0 and 1).
`report_date`	Datetime	When this summary report was generated.

Email Opens Summary

Responses for endpoints: getEmailSMTPOpenSummaryReportUser & getEmailSMTPOpenSummaryReportAccount

Keyword	Date Type	Description
`all_opens`	Integer	Total number of times that messages were opened during the specified time interval.
`msg_opens`	Integer	Total number of distinct messages that were opened during the specified time interval. If the same message was opened multiple times, that is only counted once.
`report_date`	Datetime	When this summary report was generated.

Email Clicks Summary

Responses for endpoints: getEmailSMTPClickSummaryReportUser & getEmailSMTPClickSummaryReportAccount

Keyword	Date Type	Description
`all_clicks`	Integer	Total number of times that links in messages messages were clicked on during the specified time interval.
`msg_clicks`	Integer	Total number of distinct messages had links that were clicked on during the specified time interval. If the same message had links clicked on multiple times or had multiple links cicked on, that is only counted once.
`report_date`	Datetime	When this summary report was generated.

Email SMTP Complaint Feedback Loop

Responses for endpoints: getEmailFeedBackLoopsSummaryReportUser & getEmailFeedBackLoopsSummaryReportAccount

Keyword	Date Type	Description
`complaints`	Integer	Total number of complaints coming through feedback loops during the specified time interval.
`report_date`	Datetime	When this summary report was generated.

Email Suppressions

Responses for endpoints: getUserSuppressionSummaryReport & getAccountSuppressionSummaryReport

Keyword	Date Type	Description
`count`	Integer	Total number of suppressions (or unsubscriptions) added during the specified time interval.
`report_date`	Datetime	When this summary report was generated.

User SMTP Login Failure Details

SMTP Login Failures

Responses for endpoint: getSMTPLoginFailureReportAccount

Keyword	Date Type	Description
`date`	DATETIME	When the failure or rejection happened.
`ip`	String	IP Address of the device or program that tried to login.
`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

Data Type Definitions

Type	Description
`DATE`	A specific date in the format: "`YYYY-MM-DD`". Date times are in the timezone `GMT` when used with time fields. For example the `DATE` of "`YYYY-MM-DD`" is logically equivalent to the `DATETIME` of "`YYYY-MM-DD 00:00:00`". April 1st, 2023 would be represented as "`2023-04-01`".
`DATETIME`	A specific date and time in the format: "`YYYY-MM-DD HH:MM:SS`". Date times are in the timezone `GMT`. For example, 5:13pm GMT on April 1st, 2023 would be represented as "`2023-04-01 17:13:00`".
`Enum`	Only a specific, enumerated set of values are possible.
`Integer`	Positive or negative whole number or zero.
`Float`	Floating point number.
`String`	Arbitrary text containing zero or more characters. Strings are encoded in `UTF-8`.

< API Overview Page