Email tracking, statuses & callbacks

Start here: E-mail — documentation hub.

After a message is accepted (HTTP 200 or SMTP 250), delivery and engagement events are recorded asynchronously. Use the Tracking API, portal logs, or webhooks to follow progress.

Allow 1–2 minutes after send before expecting log rows.

Tracking endpoints

Operation	Method	Path	Reference
Search logs	`POST`	`/email/tracking`	Search email tracking
Message timeline	`GET`	`/email/tracking/single/{trackingId}`	Get email tracking (single message timeline)

Base URL: https://connect.routee.net

Identifiers

Id	Source	Use
trackingId	HTTP send response	Primary key in your application
messageId	Tracking rows	Same message — either id works for lookup

Delivery lifecycle

Typical event progression on the single-message timeline (GET /email/tracking/single/{trackingId}):

`event` / `deliveryStatus`	Meaning
QUEUED	Accepted by Routee; waiting in mail pipeline
SENT	Handed off to recipient MTA or next hop
DELIVERED	Recipient server accepted the message (may include DSN)
BOUNCED	Permanent failure (bad address, policy reject, etc.)
FAILED	Could not be delivered after retries
DEFERRED	Temporary failure; may retry

Human-readable status (e.g. Queued, Delivered) appears alongside machine-oriented deliveryStatus.

SMTP diagnostics

Timeline rows may include:

Field	Description
`results[]`	SMTP attempts — `deliveryStatus`, `description`, `dsn` flag
`dsn`	Delivery Status Notification (action, status code) when available
`envelope`	SMTP envelope recipient

Useful for diagnosing bounces on SMTP sends and downstream MTA behaviour.

Engagement events (opens & clicks)

When you configure callback.eventCallback on HTTP send, Routee tracks opens and clicks. Timeline rows may include:

Field	Description
`openedCount`, `clickCount`	Counters on search/list rows
`callbackBody`	Metadata on timeline events — e.g. IP, country, device

Engagement tracking requires the HTTP API send path with event callbacks configured (or equivalent platform tracking pixels in HTML content).

HTTP send — status callback

Configure on POST /transactional-email:

{
  "callback": {
    "statusCallback": {
      "strategy": "OnChange",
      "url": "https://partner.example/webhooks/email-status"
    }
  }
}

Field	Description
`strategy`	`OnChange` — notify on every status transition; `OnCompletion` — notify when delivery reaches a final state
`url`	HTTPS endpoint Routee POSTs to

Routee POSTs JSON to your URL as delivery status changes. Treat unknown fields as optional for forward compatibility.

Retry policy: Return HTTP 200 within 2 seconds. Routee retries failed callbacks (same platform policy as Viber callbacks — up to 12 retries over 24 hours). Whitelist callbacksallow.routee.net on your firewall.

Tutorial: Receive transactional email delivery callbacks

HTTP send — event callback (open / click)

{
  "callback": {
    "eventCallback": {
      "onOpen": "https://partner.example/webhooks/email-open",
      "onClick": "https://partner.example/webhooks/email-click"
    }
  }
}

Field	Description
`onOpen`	HTTPS URL notified when the recipient opens the message
`onClick`	HTTPS URL notified when a tracked link is clicked

Event callbacks are independent of statusCallback — you may use either or both.

Polling vs callbacks

Approach	When to use
Polling `POST /email/tracking`	Simple integrations, low volume, no public webhook
Timeline GET	Support tools, manual inspection, one-off debugging
statusCallback	Push delivery updates to your backend
eventCallback	Marketing analytics, engagement funnels
Portal logs	Operators on go.routee.net — same underlying data

Search filters

POST /email/tracking accepts a JSON array of filters (same pattern as SMS tracking):

`fieldName`	Example use
`recipient`, `from`, `to`	Find mail to/from an address
`deliveryStatus`, `event`, `status`	Filter by state
`subject`	Subject line search
`date`	Combined with `dateStart` / `dateEnd` query params

Pass [] for an unfiltered date-bounded list.

SMTP sends

SMTP-submitted messages appear in the same logs as HTTP sends. There is no SMTP-equivalent of callback in the MIME session — use polling or portal logs, or send via HTTP when webhooks are required.