LuxSci API: Report Responses

SitemapHome > API > 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).

Contents

Report Response Data Definitions

Asynchronous Job Status Reports

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

Email Delivery Status Reports

KeywordDate TypeDescription
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

Sent Email Reports

KeywordDate TypeDescription
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
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 Click Reports

KeywordDate TypeDescription
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")
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 Open Reports

KeywordDate TypeDescription
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")
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 Feedback Loop Reports

KeywordDate TypeDescription
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 Suppression Reports

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

SMTP Login Failure Reports

KeywordDate TypeDescription
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

TypeDescription
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.
String Arbitrary text containing zero or more characters. Strings are encoded in UTF-8.


< API Overview Page