How do I know when an email is opened?

When you send with track_opens, AgentMail adds an invisible 1x1 pixel to your HTML body, served from your own domain. The first time a recipient’s mail client loads that pixel, the message is marked as opened.

You can see opens two ways: the opened label on the message, which you can poll or filter on, and the message.opened event, which is pushed to your webhook the moment it happens.

Open tracking is included on every plan at no extra cost. You turn it on per domain, in the console or through the API.

Setup

Open tracking is only available on a custom domain, because the pixel is served from your domain and carries your sender reputation rather than a shared one. See Custom domain setup if you do not have one yet.

Turn it on in the console

In the AgentMail Console, go to Domains:

• New domain: click Add Domain and check Open tracking.
• Existing domain: open the domain’s actions menu, choose Edit, and check Open tracking.

The console then shows the domain’s records, including the new link.<domain> CNAME.

Turn it on with the API

Enable tracking when you create the domain:

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
domain = client.domains.create(
    domain="mail.yourcompany.com",
    tracking_enabled=True,
)
for record in domain.records:
    print(record.type, record.name, record.value)

Or turn it on for a domain you already have:

domain = client.domains.update(
    domain_id="mail.yourcompany.com",
    tracking_enabled=True,
)

Either call adds a link.<domain> CNAME to the domain’s records.

Publish the CNAME record

Publish every record at your DNS provider, then wait for the domain to report VERIFIED:

domain = client.domains.get(domain_id="mail.yourcompany.com")
print(domain.status)            # VERIFIED when ready
print(domain.tracking_enabled)  # True

Once the CNAME resolves, AgentMail requests a TLS certificate for link.<domain>. Issuance usually takes a few minutes.

Two DNS settings commonly block the certificate:

• Proxied records. If your DNS provider can proxy traffic, such as Cloudflare’s orange cloud, set the link record to DNS only. A proxied record does not resolve to the CNAME target, so the domain cannot verify.
• CAA records. If your domain or a parent domain has CAA records, they must allow Amazon to issue the certificate. Add 0 issue "amazon.com" next to your existing CAA records. If you have no CAA records, there is nothing to change.

If the certificate is refused, the domain moves to FAILED with the reason tracking_certificate_failed. Fix the DNS, then turn tracking off and back on to request a new certificate.

Sending a tracked message

Set track_opens on any send, reply, reply-all, or forward:

client.inboxes.messages.send(
    inbox_id="agent@mail.yourcompany.com",
    to=["customer@example.com"],
    subject="Following up",
    html="<p>Just checking in on my last note.</p>",
    track_opens=True,
)

If the domain is not ready, the send is rejected with a 422 rather than going out untracked, so a misconfigured domain fails loudly instead of silently losing tracking.

Checking whether a message was opened

On the first open we add the opened system label to the message and to its thread. It shows up wherever you already read messages, with no extra call:

message = client.inboxes.messages.get(
    inbox_id="agent@mail.yourcompany.com",
    message_id=message_id,
)
if "opened" in message.labels:
    print("Opened")

Because it is a label, you can also filter on it. This is the simplest pattern for an agent that sends, goes away, and checks back later:

opened = client.inboxes.messages.list(
    inbox_id="agent@mail.yourcompany.com",
    labels=["opened"],
)

Reacting to an open in real time

Subscribe to the message.opened event to be notified the moment it happens. The event payload carries the open time, which the label alone does not:

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
webhook = client.webhooks.create(
    url="https://yourapp.com/hooks/agentmail",
    event_types=["message.opened"],
)
# store webhook.secret (it starts with whsec_) as AGENTMAIL_WEBHOOK_SECRET

AgentMail delivers webhooks through Svix, so verify each request’s signature against the raw request body before you trust it. These handlers use the svix library (pip install agentmail flask svix or npm install express svix):

import os
from agentmail import MessageOpenedEvent
from flask import Flask, request
from svix.webhooks import Webhook, WebhookVerificationError
app = Flask(__name__)
webhook = Webhook(os.environ["AGENTMAIL_WEBHOOK_SECRET"])
@app.route("/hooks/agentmail", methods=["POST"])
def agentmail_webhook():
    # verify the signature on the raw body, not on parsed json
    try:
        payload = webhook.verify(request.get_data(), request.headers)
    except WebhookVerificationError:
        return "", 400
    if payload["event_type"] == "message.opened":
        event = MessageOpenedEvent(**payload)
        print(event.open.message_id, event.open.timestamp)
    return "", 204
if __name__ == "__main__":
    app.run(port=3000)

See Webhook events for every event type and Verifying webhooks for more on signature verification.

What open tracking can and cannot tell you

Open tracking is a directional signal, not proof that someone read your email. This is true of every pixel-based implementation, not just ours, and it is worth designing around:

• Opens can be missed. Many mail clients block remote images by default, and Apple Mail Privacy Protection can suppress loads. A message without the opened label was not necessarily unread.
• Opens can fire without a human. Gmail and some security scanners pre-fetch images through a proxy, which can register an open within seconds of delivery. Treat a very fast open with suspicion.

If your agent takes action on an open, such as sending a follow-up, design it to tolerate both a missed open and a machine-triggered one.

Current limits

• First open only. The label and the event fire once per message. Repeat opens are not counted.
• One pixel per message, not per recipient. A message sent to several recipients fires once when any of them opens it, and the event does not say which one. Send separate messages if you need per-recipient attribution.
• Immediate sends only. track_opens is honored on send, reply, reply-all, and forward. It is not yet supported on drafts or scheduled sends.
• Custom domains only. Tracking is not available on shared AgentMail domains.
• No click tracking yet.