Email open tracking API for AI agents
Updated 18 November 2026
Short answer: one call creates a pixel, one tag goes in the email, and opens come
back through a cursor-based feed or HMAC-signed webhooks. Agents can sign themselves up
with POST /signup. The same account is also available as a remote MCP server
at https://p.didtheyopen.com/mcp. The full instructions an agent should
follow are at agent.md (guide version 7).
This page is the endpoint overview. For the Gmail or Outlook send path, see the Gmail and Outlook guides. For what an open means, see How accurate is email open tracking?.
Base URL and auth
- Base URL:
https://p.didtheyopen.com -
Agent key:
dto_a_…, stored asDIDTHEYOPEN_API_KEY. It can create pixels, check the suppression list and see opens. It cannot pause, delete or manage keys. Never log it, never put it in a URL, never send it to a recipient. -
MCP (Streamable HTTP):
https://p.didtheyopen.com/mcpwith headerAuthorization: Bearer <agent key>. Tools:didtheyopen_signup,didtheyopen_track_email,didtheyopen_check_email,didtheyopen_new_opens,didtheyopen_account. Without a key, only signup works.
The calls
-
POST /signup: new account, no email needed. Returns an agent key, a manage key, a dashboard login key and a dashboard URL, once. Every key is shown once and cannot be recovered. Give the owner the dashboard login and the manage key in a private channel. Keep the manage key yourself only if the owner wants you to register a webhook. -
GET /v1/me: plan, trial left,can_create, checkout links, today's usage, andguide.versionplusguide.url. If the guide version is newer than the one you follow, fetchguide.urland switch. -
POST /v1/messageswithIdempotency-Key(same value asclient_ref): body{ client_ref, sender_label, label, expires_in_days }. Returnspixel_urlonce. Reuse the sameclient_refand idempotency key after a network error; you get the same pixel, never a duplicate. -
POST /v1/messages/<id>/links:{ urls: [every link in the HTML, in order] }. Replace eachhrefthat comes back with atracked_url. Leave mailto, unsubscribe, and visible link text alone. A person's click in a browser counts as opened. A click fetched by Apple's relay or another mail proxy, or from an Apple or Google network with a normal browser, is labelledprefetch_likelyorunknownand not counted. Skip only when the owner says not to track links. If this call fails, send with the original links and the pixel. -
GET /v1/messages/by-ref/:client_ref:event_count(every recorded image load, opened or not),last_event_at, and aninsightwhoseopenscounts loads labelledopened(a person's click is labelledopenedtoo), with a plain-languageheadline. -
GET /v1/messages/<id>/events: each load withreceived_at,load_label,classificationandclient_family. -
GET /v1/events?since=: every new load across all messages, exactly once. Storenext_sinceand pass it back. Poll every 10 to 15 minutes. Addsummary=1for a per-emailinsight. This is the scheduled feed; with MCP it isdidtheyopen_new_opens. -
POST /v1/webhooks: register once with a manage key ({ "url": "https://<your-agent-endpoint>" }). Thesecret(whsec_…) is shown once. Notable opens arrive as a signed POST (X-DidTheyOpen-Signature,X-DidTheyOpen-Timestamp,X-DidTheyOpen-Delivery). The signature isv1=plus hex HMAC-SHA256 of<timestamp>.<raw body>, keyed with the full secret string, prefix included. Drop timestamps older than 5 minutes and repeateddelivery_ids, answer 2xx within 5 seconds. Failures are retried for about 15 hours. Use the pull feed to reconcile after downtime. -
POST /v1/suppressions/check: optional. SHA-256 hex hashes of the lowercase recipient address and domain.{ "suppressed": true }means send untracked. GET /v1/messages?limit&cursor: recent messages, newest first.
Insert exactly this tag at the end of the HTML body, before </body>:
<img src="PIXEL_URL" alt="" width="1" height="1" border="0" style="display:block;width:1px;height:1px;border:0;overflow:hidden">
One pixel per email. Do not convert plain-text emails to HTML just to carry it.
Example
curl -X POST https://p.didtheyopen.com/v1/messages \
-H "Authorization: Bearer $DIDTHEYOPEN_API_KEY" \
-H "Idempotency-Key: proposal-dana-1" \
-H "Content-Type: application/json" \
-d '{"client_ref":"proposal-dana-1","sender_label":"work","label":"Dana Levi"}'
The 201 response includes pixel_url. After sending, poll
GET /v1/events?since=<next_since>&summary=1 and tell the owner only
when insight.notable is true.
Trial, errors and privacy
New accounts get 25 tracked emails free, with no card. Then Personal is $9/month (up to
300 tracked emails a day) or Developer is $29/month (up to 2,000 a day). A tracked message
and its opens are deleted after 30 days by default, or sooner if you set a shorter expiry,
from when the message is created. When the trial is used up,
POST /v1/messages returns 402 payment_required with checkout
links; send the email untracked and tell the owner once.
Other errors: 401 bad key · 403 wrong scope ·
409 client_ref_exists · 409 idempotency_conflict ·
429 quota_exceeded (daily cap, wait for 00:00 UTC) ·
429 rate_limited / signups_full · 503 storage
unavailable (retry later with the same client_ref). Every error is
{ "error": { "code", "message" } }.
No recipient addresses, subjects, content or IP addresses are stored.
Questions
Is there an OpenAPI file?
Yes. The API reference is at /docs and the OpenAPI document is at
/openapi.json. agent.md is the
integration guide; GET /v1/me tells you when that guide has a new
version.
Do I have to host a webhook?
No. If you have no public HTTPS endpoint, pull the scheduled feed every 10 to 15 minutes. Webhooks are the push path, and they need a manage key to register.
Can the agent sign itself up?
Yes. POST /signup needs no email. The agent stores the agent key and
gives the owner the dashboard login and manage key once, in a private channel.