Follow

Logs API for Email

Logs API for Email

This REST API enables you to download records with information about the status of an email that Kahuna tried to send to a user. This log record does not contain the contents of the email itself, but information about what happened when Kahuna tried to send the email. A single email can lead to multiple log records.

API Request

Request URI and Header

Request URI - HTTP POST

To target the production environment: https://tap-nexus.appspot.com/api/kahunalogs?env=p

To target the sandbox environment: https://tap-nexus.appspot.com/api/kahunalogs?env=s

Request Header

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings
Request Body

The request body contains data that controls which log records the server returns. The fields are described below.

Fields
timestamp

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

The server returns records for the date specified in the timestamp. For this date, the returned records have a timestamp starting at the specified time and ending on or before 23:59:59 of the specified date. Although most known date and time formats work, you can always use the format:

m/dd/yyyy h:mm

Elements in bold are entered exactly as written.

  • m is the month number (1 or 2 digits)
  • d is the day number (1 or 2 digits)
  • yyyy is the four-digit year
  • h is the hour in 12-hour format
  • mm is minute

You must convert the time to its UTC equivalent. All Kahuna timestamps are stored in UTC. The API does not convert the timestamp value to UTC before comparing it to log records.

cursor

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

This is the identifier of a previously returned cursor. Cursor identifiers are temporary and can expire at any time. See Response Body, below.

number_of_records Required. The number of records to retrieve. The number must be greater than 0 and less than or equal to 1000.
categories_to_return

Required.

For email logs, set "categories_to_return" : ["email"]

For push logs, set "categories_to_return" : ["push"]

For in-app messages, set "categories_to_return" : ["inapp"]

For user merge logs, set "categories_to_return": ["user_merge"].

You can retrieve other categories except for user_merge in the same request by adding their categories to the array. However, you cannot combine the user_merge category with other categories.

Example
{
       "number_of_records" : 1000,
       "timestamp" : "07/30/2016 00:00",
       "categories_to_return" : [ "email" ]
}

API Response

Kahuna responds to a logs request with a numeric code and a response body.

HTTP Response Codes

The HTTP response code returned from a request indicates the overall status of the request.

Codes
200 Successful API call.
400

Bad request. Some part of the request is malformed. For example, the specified number of records is invalid.

401

Authentication or authorization failure. The credentials supplied with the request are invalid.

409 Not authorized. The credentials are not authorized to use the Logs API.
500 Kahuna internal server error.
Response Body

The response body is a JSON object that contains additional information about the status of the request, as well as an array of log records. If the server cannot deliver all the records that match your request in a single response, the response body contains two fields in addition to the array of log records:

  • more_records is a boolean value that is set to true if more records are on the server.
  • cursor is a string value that points to the set of remaining records.

To continue retrieving records for your original request, add the value of cursor in the request body and send a new request. The server responds with a new set of records. This process continues until one of these conditions is met:

  • The server has sent all the records that match the day you specified in the timestamp field in the request body.
  • The number of records sent is equal to the value of number_of_records you specified in the request body.
  • You stop sending log requests containing the value of cursor returned to you in the response body.

The fields in the response body and individual log records are listed below.

Fields
success

If the request fails, this field is set to false. If the request succeeds, this field is not present.

error

If an error occurs, provides a human-readable error message. If no error occurs, this field is not present.

error_code

If an error occurs, provides the HTTP error code. If no error occurs, this field is not present.

error_detail

If an error occurs, provides more detailed information about the error. If no error occurs, this field is not present.

more_records

If more records are available for download this field is set to true; otherwise the field is set to false.

cursor

If the server cannot deliver all the records that match your request in its initial response, it sets more_records to true and returns a cursor value that points to more records on the server. To retrieve these records, move the value of cursor to the cursor field in the request body and re-issue the request.

email

An array of JSON objects representing the log records.

If the request is well-formed, but no records match the time and date criteria, the array is empty. The format of the individual record is:

action

The fields in the log record vary, depending on the value of action. The possible values are:

email The email was successfully sent to the target user.
more engaged As a result of the email, the user re-opened your app.
email_goal After Kahuna sent an email and confirmed that the user received it, the user took some action that achieved a goal in the campaign that generated the email.
precomplete The user completed a campaign goal before Kahuna sent the email, so no email was sent.
open The user opened the email.
click The user clicked in the email.
rate_limited The cooldown period hadn't expired when the system tried to send an email to the target user. For example, suppose one campaign sends an email to a user, then 30 minutes later another campaign starts to send an email to the same user. If the cooldown period for the second campaign is four hours, the user isn't eligible for contact. The system doesn't send out a second email, and at the same time it records a rate_limited log record.
user_missing The system added a user to a campaign, but when the system started to send emails, the target user ID was no longer known to the system.
no_longer_valid The user no longer meets the campaign criteria. Between the time you created the campaign and the time the system started to send emails, one or more of the user's attributes changed, disqualifying them from the campaign.
blocked An email error occurred during the delivery process.
action_category

If the value of action is one of the following, action_category is not present:

  • precomplete
  • more engaged
  • email_goal
  • user_missing

For all other values of action:

email

sent—the email was successfully sent to the user.

Queued—the email is queued for sending.

Note: Some successfully delivered emails include a queued notation in the SMTP response. These emails has been delivered to the recipient as expected, but might require additional processing before they land in a recipient's mailbox. For example, sometimes email can be sent much faster than recipient servers are able to accept or process. In many cases, the time of day and overall email traffic to the ISP or recipient server can affect how quickly recipients are able to receive and process your email.

scheduled—the email is scheduled to be sent.

open open—the user opened the email.
click click—the user clicked in the email.
rate_limited

rate_limited—the action detail is one of the following:

  • Email message will not be sent because a message has already been sent to user user_id within the last x seconds.
  • Email message will not be sent because a message has just been sent to email address address for campaign campaign_name.

The system just sent this user an email for this campaign, or the system sent an email for this campaign and the cooldown period has not yet expired.

blocked

blocked—the user is on the don't send list.

unsub—the user already unsubscribed from the email list.

hard_bounce—heuristics determined that a permanent error (such as an invalid mailbox) occurred. The email remains blocked for up to six months.

soft_bounce—heuristics determined that a temporary error (such as a full mailbox) occurred. The email will probably be resent in a couple of days.

spam—the destination email system classified the email Kahuna sent as spam. Kahuna will no longer try to send the email.

reject—the target email address was already on a blacklist. The current email is not sent.

no_longer_valid no_longer_valid—between the time you created the campaign and the email was sent, one or more user attributes changed that disqualified the user from the campaign.
action_detail

This field is present for the following values of action:

  • precomplete
  • email_goal
  • blocked (but only if the user is on a blacklist because of prior email problems)
  • rate limited

For all other values of action, the action_detail field is not present.

message

If the target user of the email is part of a control group, the field is set to control; otherwise, it is set to unknown.

campaign

If the value of action is more engaged or email_goal, this field is not present. Otherwise, this field contains the campaign name as it's displayed in the Dashboard.

campaign_id

The Kahuna internal ID for the campaign message. Identifies the message that was sent.

user_id

Kahuna assigns this GUID to the device user when your app first connects to Kahuna, even if the user doesn't provide credentials to your app (anonymous user).

email

If the value of action is more engaged or email_goal, this field is not present. Otherwise, it contains the email address to which the message was sent.

dev_id

This field is only present if the value of action is more engaged or email_goal.

credentials

A list of target user credentials (except for device id). If the value of action is one of the following, this field is not present:

  • user missing
  • open
  • click

For all other actions, this field contains an array of user credential values for the target of the email. Although a campaign might select users by matching only a few credentials, the log record contains all of the credentials for the target user.

timestamp

The date and time the log record was created. The format is "YYYY-MM-DD HH:MM:SS.SSSSSS". The time is UTC.

os

The platform identifier for the target device. Possible values are:

  • android
  • ios
Example

The following JSON snippet shows an example of email records in a response.

{
  "email": [
        {  
         "timestamp": "2016-06-01 23:41:24.731020",
         "campaign_id": 85440012,
         "action_category": "unsub",
         "action": "blocked",
         "message": "unknown",
         "email": "user@email.com"
       },
         {
          "user_id": 164838001,
          "campaign": "MyCampaign",         
          "timestamp": "2016-06-01 23:41:24.731020",
          "campaign_id": 7610011,
          "action_category" "sent",
          "action": "email",
          "message": "{{last_name|default:\"fsdf\"}}",
          "email": "user@email.com"
       }
   ]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments