Retrieve email events

What happened to your mail after you sent it. Everything is scoped to the sending domain your key belongs to, newest first.

Query parameters

All optional. Send none and you get the 25 most recent events.

limit integer optional: How many events to return. 1 to 100, default 25.
offset integer optional: How many to skip. Default 0. With total, this is your pagination.
event string optional: Return only this event type. One of the names below.
message_id string optional: Everything that happened to one message. Takes the id from a send response, with or without the msg_ prefix.
start string optional: Earliest event to return. A Unix timestamp in seconds, or an ISO-8601 date.
end string optional: Latest event to return. Same formats.

Event types

A message usually produces several. The ones that name a stage are the useful ones when something goes wrong: a message rejected by the system never reached the network, while one rejected by the sending infrastructure did and was refused.

accepted Pharos took the message.

rejected Pharos refused it before it left.

accepted-by-system The message passed internal checks and was queued.

rejected-by-system Internal checks refused it. The message never reached the network.

accepted-by-mta The sending infrastructure took it for delivery.

rejected-by-mta The sending infrastructure refused it. Usually the address or the content.

delivered The receiving server accepted it. As close to "arrived" as SMTP gets.

failed Delivery failed permanently. The address or the receiving server refused it.

opened The recipient opened it. Only when open tracking is on.

clicked The recipient clicked a link. Only when link tracking is on.

complained The recipient marked it as spam. Counts against the rate in the AUP.

unsubscribed The recipient opted out.

Paging

total is the number of events matching your filter, not the number returned. Ask for the next page by adding your limit to offset until offset reaches total.

Events arrive continuously, so a long page-through of a live filter can shift underneath you. Pin end to the moment you started if you need a stable set.

Retention

Events are kept for 120 days, on every plan including the free one. A start earlier than that returns what exists rather than an error.

Errors

The same shape and the same codes as the rest of the API: 400 names the parameter it did not like, 401 means the key, 429 means slow down. See errors and limits.

RequestcURL

curl -G https://api.pharos.email/v1/events \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -d "limit=50" \
  -d "event=delivered"

Response200 OK

{
  "total":  150,
  "limit":  50,
  "offset": 0,
  "events": [
    {
      "event":       "delivered",
      "occurred_at": "2026-09-12T11:33:20.000Z",
      "from":        "receipts@yourapp.com",
      "to":          "customer@example.com",
      "subject":     "Your receipt from Acme"
    }
  ]
}

Useful queriescURL

# everything that happened to one message
curl -G https://api.pharos.email/v1/events \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -d "message_id=msg_2f8Kq1Zx"

# complaints in the last week
curl -G https://api.pharos.email/v1/events \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -d "event=complained" \
  -d "start=2026-09-05"