Track Email Opens From Your Agent's Outreach

You built an outreach agent, it sent 80 follow-ups this week, and you have no idea what happened to any of them. Did the prospect open the message? Click the demo link? Is the silence a "no" or a spam-folder problem? Without engagement signals, your agent is firing into the void and your follow-up logic is guesswork.

The fix has two parts: turn tracking on when you send, and subscribe to the webhooks that report what recipients do.

Tracking starts at send time, not after

Opens, clicks, and replies are only reported for messages sent with tracking enabled — you can't retroactively track a message that's already out. On the Send Message request, pass a tracking_options object with three booleans plus an optional label that gets echoed back in every notification:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "subject": "Quick follow-up on your trial",
    "body": "Thanks for trying us out. Reply or <a href=\"https://example.com/demo\">book a demo</a> when ready.",
    "to": [{ "name": "Kim Townsend", "email": "kim@example.com" }],
    "tracking_options": {
      "opens": true,
      "links": true,
      "thread_replies": true,
      "label": "trial-followup-q2"
    }
  }'

The label is the piece agents should lean on: stamp it with your campaign ID or contact ID and every later notification carries it, so your handler matches events back to outreach state without storing a message-ID mapping. One caveat before you test: message tracking needs a production application — trial accounts get "Tracking options are not allowed for trial accounts" back.

Three triggers, one endpoint

Engagement events arrive over webhooks. Subscribe one HTTPS endpoint to all three triggers — message.opened, message.link_clicked, and thread.replied:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/webhooks/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "trigger_types": ["message.opened", "message.link_clicked", "thread.replied"],
    "webhook_url": "https://yourapp.com/webhooks/nylas",
    "description": "Email engagement tracking"
  }'

One activation detail trips people up: when you create the webhook, Nylas sends a GET request with a challenge query parameter, and your endpoint has to echo it back before the subscription goes live. If your route only handles POST, the webhook never activates and you'll be staring at zero events wondering why.

Each payload names the tracked message's ID, your label, and a recents array holding the last 50 events for that message — each stamped with a timestamp, IP, and user agent. Return 200 OK within 10 seconds or the delivery counts as failed and gets retried, which an idempotency-naive agent will misread as a second open.

A minimal handler that covers the challenge handshake and routes on trigger type:

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/nylas", methods=["GET", "POST"])
def nylas_webhook():
    if request.method == "GET":
        return request.args.get("challenge", ""), 200

    event = request.get_json()
    trigger = event["type"]
    message_id = event["data"]["object"]["message_id"]

    if trigger == "message.opened":
        record_open(message_id)        # soft signal — log it, don't act on it
    elif trigger == "message.link_clicked":
        warm_up_sequence(message_id)   # real human action
    elif trigger == "thread.replied":
        stop_sequence(message_id)      # strongest signal — hand off the thread

    return "", 200

The three trigger names map cleanly onto agent decisions, which is why routing on event["type"] at the top of the handler beats funneling everything into one "engagement" counter.

The three signals are not equally honest

Here's where outreach agents go wrong: treating an open as intent.

Open tracking works by embedding a transparent one-pixel image that the recipient's client loads. Corporate gateways and privacy-focused clients block remote images, silently dropping real opens. Worse, prefetching proxies do the opposite — Apple Mail Privacy Protection, on by default since iOS 15, pre-loads images through Apple's proxy and registers an open whether or not a human read anything. Apple's share of the email client market sits near 50%, so a large slice of your open data is inflated. Report opens as "opened at least once," never as a read count, and never let your agent escalate on an open alone.

Clicks are sturdier: a click is a real human action. With links: true, every valid HTML anchor in the body gets rewritten to a tracking URL (capped at 100 tracked links per message, and URLs carrying login credentials are skipped so authenticated destinations don't break). Replies, via thread.replied, are the strongest signal of the three — unambiguous intent.

A sane decision policy for an outreach agent: open → no action, maybe shorten the follow-up interval; click → move the contact to a warmer sequence; reply → stop the sequence immediately and hand the thread to your reply-handling logic.

A caveat if your agent sends from its own mailbox

If your outreach agent runs on a Nylas-hosted Agent Account — the beta feature that gives an agent its own dedicated mailbox rather than a connected Gmail or Outlook grant — know that native message tracking isn't available on its direct API sends. message.opened and message.link_clicked aren't emitted for messages sent through POST /messages/send on those accounts. Deliverability visibility comes instead from the send-side triggers: message.send_success, message.send_failed, and message.bounce_detected.

In practice that's a reasonable trade. Send-side triggers tell you what actually got delivered or bounced, replies still land in the agent's inbox and fire message.created, and reply-based routing — the strongest signal anyway — works exactly the same. The tracking flags above apply when you're sending through connected provider grants, which is how a lot of outreach tooling runs.

Two smaller gotchas

Each trigger also ships a .legacy variant — message.opened.legacy, message.link_clicked.legacy, thread.replied.legacy — for applications on the older notification format. New integrations should subscribe to the non-legacy names; mixing the two gets you duplicate events with different payload shapes, which is a miserable thing to debug.

And remember what tracking actually does: it rewrites your message content and pixels your recipients. The flags work the same whether the sending grant is Google, Microsoft, or another provider, so one send path covers your whole sender base — but that also means your disclosure obligations follow every message. Honor consent, disclose tracking where your jurisdiction requires it, and don't track links that carry sensitive data.

Wire the weakest signal last

Build the reply path first, clicks second, opens last — the reverse of how most teams do it, and the order that matches signal quality. Full payload schemas and per-provider behavior are in the tracking recipe.

Next step: add tracking_options to one live campaign, log the three trigger types for a week, and compare your open rate against your click rate. If they tell wildly different stories — which signal is your follow-up logic currently trusting?

推荐订阅源

DEV Community