Table of Contents

Logs

Track a sent message: openings, downloads, signatures. You can read the log of one message, or the logs of every message over a period.

Prerequisites

The log of one message

GetLog expects a single identifier: the tracking number (TrackingID) or the message identifier (MessageID). With both, or neither, it returns status 400.

var args = new GetLogArgs(endpoint, serial, apiUser, apiPassword)
{
    TrackingID = trackingId   // response.RecipientsAnswer[i].Answer.TrackingID
};

GetLogResponse response = LogsHelper.GetLog(args);

if (response != null && response.Status == 200 && response.Log != null)
{
    MessageLog log = response.Log;
    // log.OpenStatus, log.OpenTime, log.IsSignProcessCompleted...
}

The logs of a period

GetLogs returns the logs of every message sent between two dates (From, To).

DateTime end = DateTime.UtcNow;   // in UTC: see Time zone
var args = new GetLogsArgs(endpoint, serial, apiUser, apiPassword, end.AddDays(-7), end);

GetLogsResponse response = LogsHelper.GetLogs(args);

if (response.Status == 200)
{
    foreach (MessageLog log in response.Logs)
        Process(log);
}

The period cannot exceed 6 months per call: beyond that, the server returns status 400. Keep it short anyway: the response is not paginated and can become very large.

Time zone

Your account has a time zone: Eastern Time, unless you changed it. The server reads the period's dates in that time zone and expresses the logs' dates in it. One exception: if the start date arrives in UTC, the period is read in UTC and the logs' dates are in UTC.

SDK Dates to pass Logs' dates
.NET In UTC (DateTime.UtcNow) UTC
Python With or without a time zone: the SDK sends them in UTC. Without a time zone, a date is the machine's local time UTC
PHP Any DateTime: the SDK sends it in UTC UTC
Warning

In .NET, a DateTime.Now date is sent with its UTC offset: the server first brings it to its own clock, then reads it in your account's time zone, and the period can be shifted by the difference between the two. Pass UTC dates.

Content of a log

In Python and PHP, each log is a dictionary (associative array) whose keys are the names below, as is. Dates are ISO 8601 strings, and statuses are numbers.

Field Content
OpenStatus Message status: see the next table.
OpenTime Number of openings.
CreatedDate, LastUpdate Send date, date of the last activity.
Recipient Recipients, separated by commas.
FromEmailAddress Sender's address.
Subject Message subject.
MsgType 1: message; 2: reply.
TrackingId Tracking number.
LogFiles Attachments: FileName, OpenStatus, OpenTime (number of downloads), FileSize, IsFileToSign.
Activities History: Date, Status, RemoteIP (IP address behind the activity), Reference.
IsContainsSignsFiles The message contains files to sign.
IsSignProcessCompleted The signature is complete.
Value Status Meaning
0 NotRead Not read yet.
1 Read Read.
2 Retreive Retrieved.
3 Destroy Destroyed as a security measure.
4 Try Opening attempt.
5 ShowInMailbox Email displayed in a mailbox.
6 Error Error on the message.
7 InitiateTheAction Sender's action (send, file upload).
8 Processing Being sent or processed.
9 Failed Send failed.
10 Cancelled Recipient cancelled: no longer has to open or sign.

Good to know

  • Another user. UserLogSerial gives the logs of another user of your organization; leave it empty for your own. Your own logs require no permission; another user's logs require the ViewLogs or ViewAdminLogs permission, otherwise status 403.
  • Personal information. A log contains email addresses, the subject and IP addresses. Do not copy it into your technical logs, restrict who can read it and plan its retention period.
  • Errors. In .NET, the error text of LogsHelper.GetLogs may contain a full technical trace: never show it to a user.

GetLog may return null when the key exchange fails: test it before reading the status, as in the example.

Pass identifiers as uuid.UUID: a string makes the call fail without raising an exception.

Common errors

Symptom Likely cause Solution
Status 400 (GetLog) Both identifiers given, or neither Pass the tracking number or the message identifier.
Status 0 (GetLog) or 500 (GetLogs) Error caught by the SDK: malformed identifier, network Check the identifiers' type and the connection.
Status 400 (GetLogs) Period longer than 6 months Split the period.
Status 403 Another user's logs, without the permission Ask an administrator of your organization for ViewLogs or ViewAdminLogs.
Logs missing at the start or end of the period .NET: dates passed with DateTime.Now Pass UTC dates: see Time zone.
Very slow response or timeout Period too long Split the period.
Python: AttributeError on log.open_status Logs are dictionaries Read log["OpenStatus"].
Fields MessageStatus, OpenCount, SentDate not found Names from a former guide Use the fields from the table above.

Next