Guides & Tutorials

Subscriber action log

GET /api/history.php

Endpoint can be used to request a list of subscriber actions in time sorted order (older actions first).

Request parameters

Note! Either since_seq_id, or start_at and end_at parameter(s) must be provided.

Parameter Value
since_seq_id Return results only after specified action sequence number.

In order to fetch actions from first, please query actions with value 0.

Default: None
start_at Actions range start date.

Value has to be an UNIX timestamp and in UTC time.

Default: None
end_at Actions range end date.

Value has to be an UNIX timestamp and in UTC time. Must not be less than start_at value.

Default: None
offset Page number.

Value of 0 returns actions from 0 to 10000. 1 gives 10001 to 20000 etc. Offset cannot be used with since_seq_id parameter.

Default: 0
limit Number of actions to return per request.

Value cap is 10000. Limit must be set when querying actions by since_seq_id parameter.

Default: No limit
actions Limit actions to return.

Possible values are: bounce, click, complaint, create, delete, modify, optin, optout, send and view.

Default: All

Action types

Parameter Value
bounce Delivery to subscriber’s email address failed.

Field value contains the SMTP response code received. The most common response codes
click Subscriber clicked on a link. Field value contains the URL of the link.
complaint Subscriber reported email as spam.
create Subscriber was added to the Smaily database.
delete Subscriber was deleted from Smaily database.
modify Subscriber’s data was changed.

Field value contains all fields in the Smaily database.
optin Subscriber subscribed.
optout Subscriber unsubscribed.
send Subscriber received an email.
view Subscriber viewed/opened a message.

Field value contains information about contact’s OS, email client, IP-address and country.

Response parameters

Note! Response is ordered by seq_id when querying actions by since_seq_id, and by time when requested using start_at and end_at.

Parameter Value
seq_id Action sequence number.

Value is a 64-bit unsigned long.

Parameter is only returned when querying actions by since_seq_id.
email Subscriber's email address.
time Action date and time.

Formatted as YYYY-MM-DD HH:MM:SS, and presented in Europe/Tallinn timezone.
campaign_id Campaign ID.

Default: null
campaign_name Campaign name and message subject.

Default: null
value Additional information about the action.
action Action type.

Example

Example 1

$ curl -X GET -u "${USERNAME}:${PASSWORD}" \
  "https://${SUBDOMAIN}.sendsmaily.net/api/history.php?start_at=1621288800&end_at=1621252800"

(JavaScript/JSON)

[
  {
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:11",
    "campaign_id": null,
    "campaign_name": null,
    "action": "optin",
    "value": ""
  },
  {
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:17",
    "campaign_id": null,
    "campaign_name": null,
    "action": "modify",
    "value": "foo=bar; name=; lastname=Bar"
  },
  {
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:11",
    "campaign_id": 1,
    "campaign_name": "My first campaign",
    "action": "click",
    "value": "https://domain.tld"
  }
]

Example 2

$ curl -X GET -u $ curl -X GET -u "${USERNAME}:${PASSWORD}" \
  "https://${SUBDOMAIN}.sendsmaily.net/api/history.php?since_seq_id=10&limit=10"

(JavaScript/JSON)

[
  {
    "seq_id": 11,
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:17",
    "campaign_id": null,
    "campaign_name": null,
    "action": "optin",
    "value": ""
  },
  {
    "seq_id": 12,
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:11",
    "campaign_id": null,
    "campaign_name": null,
    "action": "modify",
    "value": "foo=bar; name=; lastname=Bar"
  },
  {
    "seq_id": 13,
    "email": "subscriber@domain.tld",
    "time": "2021-05-17 14:05:11",
    "campaign_id": 1,
    "campaign_name": "My first campaign",
    "action": "click",
    "value": "https://domain.tld"
  }
]
Menu