Source: https://cli.nylas.com/guides/email-read-receipts-api

# Email Read Receipts: API Options Compared

You want to know whether the email you sent was opened. Four mechanisms claim to answer that, and they're wildly unequal: a 1990s header standard most clients ignore, a Gmail feature locked to Workspace admins, an Outlook property that recipients can decline, and pixel tracking with webhooks — the only one that works across providers. This guide compares all four and wires up the working one from the terminal.

Written by [Nick Barraclough](https://cli.nylas.com/authors/nick-barraclough) Product Manager

Updated June 6, 2026

> **TL;DR:** The Gmail API has no read-receipt endpoint, RFC 8098 MDNs are voluntary, and Outlook's `isReadReceiptRequested` asks the recipient's permission. The mechanism that works programmatically is open tracking: [`nylas email send --track-opens`](https://cli.nylas.com/docs/commands/email-send) plus a webhook on the `message.opened` trigger — with the caveat that Apple Mail Privacy Protection inflates open counts.

Command references used in this guide: [`nylas email send`](https://cli.nylas.com/docs/commands/email-send), [`nylas webhook create`](https://cli.nylas.com/docs/commands/webhook-create), and [`nylas webhook server`](https://cli.nylas.com/docs/commands/webhook-server).

## Does the Gmail API support read receipts?

No — the Gmail API has no read-receipt endpoint, parameter, or event. Read receipts exist in Gmail only as a Workspace feature controlled by administrators, and Google's [read receipt documentation](https://support.google.com/a/answer/1385059) is blunt about scope: "Read receipts are only available to work or school accounts. They don't work with personal Gmail (@gmail.com) accounts." The receipt itself arrives "as an email with the time and date of when your message was opened", a human-facing message rather than a structured API event.

For developers that closes the native door twice over: consumer recipients can't return receipts at all, and even in Workspace there's nothing to poll or subscribe to. Anyone searching for "gmail api read receipt" ends up at one of the 3 remaining mechanisms below.

## What is an RFC 8098 message disposition notification?

A Message Disposition Notification (MDN) is the email standard's own read receipt, defined in [RFC 8098](https://datatracker.ietf.org/doc/html/rfc8098): the sender adds a `Disposition-Notification-To` header, and the recipient's client may send back a structured report when the message is displayed. The operative word is "may" — the RFC makes returning the notification entirely optional, and the receiving client decides whether to ask the user, comply silently, or ignore the header.

In 2026 practice, mainstream consumer clients ignore it: Gmail's web interface offers no MDN response for personal accounts, and corporate clients typically prompt the user. That makes the header worth setting only in closed environments (internal Exchange deployments, EDI-style B2B flows where both sides agree to honor it) and worthless as a general delivery signal. It costs 1 header line, and that's about what it returns.

## How do read receipts work in Outlook and Microsoft Graph?

Outlook implements receipt requests as message properties. The Graph [message resource](https://learn.microsoft.com/en-us/graph/api/resources/message) exposes 2 receipt-request booleans (`isReadReceiptRequested` and its sibling `isDeliveryReceiptRequested`) that you set when creating a message. When the request is honored, the receipt comes back as a separate email to the sender, in the same out-of-band, human-readable format as Gmail's Workspace feature.

The recipient's client still holds the veto: Outlook's default settings let users approve or decline each receipt, and organizations can disable responses centrally. Treat `isReadReceiptRequested` as a politeness flag with meaningful response rates only inside organizations that mandate it. Separately, the message resource's `isRead` property is reliable — but it tracks read state in mailboxes you have Graph access to, which is mailbox monitoring, not a receipt from an external recipient.

## How does webhook-based open tracking work?

Open tracking embeds a unique, invisible 1-pixel image in the outbound message; when the recipient's client loads remote images, the image request fires and the provider emits a structured event. Unlike the 3 mechanisms above, nothing asks the recipient's client for cooperation beyond image loading, which is why this is the mechanism marketing and sales tooling actually ships. The [Nylas message tracking documentation](https://developer.nylas.com/docs/v3/email/message-tracking/) covers the full event model: opens, link clicks, and thread replies, each delivered as a webhook.

From the CLI, tracking is 2 flags on send and 1 webhook registration. The `--track-label` flag tags the send so downstream events identify which campaign or workflow they belong to.

```bash
# 1. Register a webhook for tracking events (one time)
nylas webhook create \
  --url https://api.example.com/nylas/webhooks \
  --triggers message.opened,message.link_clicked,thread.replied

# 2. Send with tracking enabled
nylas email send \
  --to prospect@example.com \
  --subject "Proposal follow-up" \
  --body "Attached is the revised proposal." \
  --track-opens --track-links \
  --track-label "q2-proposals"

# 3. During development: receive events locally
nylas webhook server --no-tunnel
```

Each open event arrives as a `message.opened` webhook within seconds of the image request, carrying the message ID and timestamp. The [webhook events reference](https://cli.nylas.com/guides/email-webhook-events-reference) documents payload shapes, the 3-attempt retry policy, and HMAC signature verification — verify before you parse.

## How reliable is open tracking in 2026?

Open tracking over-reports and under-reports at the same time, and you should size decisions accordingly. Apple's [Mail Privacy Protection](https://support.apple.com/guide/iphone/use-mail-privacy-protection-iphf084865c7/ios) (on by choice since iOS 15 in 2021) "prevents senders from seeing if you've opened the email message they sent you" by proxying remote content, which registers opens regardless of whether a human looked. In the other direction, clients that block remote images entirely produce real reads with no event.

The honest interpretation model: a `message.opened` event is a strong signal on a per-message basis for non-Apple-Mail recipients, aggregate open rates are directional rather than precise, and `message.link_clicked` is the high-confidence signal — a click can't be proxied into existence. Build alerting and follow-up automation on clicks and replies first, opens second.

## Which read receipt mechanism should you use?

The 4 mechanisms reduce to one decision: do you control both ends of the conversation? If yes (internal mail, B2B with agreed tooling), native receipts work. If no, pixel tracking with webhooks is the only mechanism that returns structured data without recipient opt-in.

| Mechanism | Programmatic? | Works across providers? | Recipient can block? |
| --- | --- | --- | --- |
| RFC 8098 MDN header | Yes (header only) | Rarely honored | Yes — default in most clients |
| Gmail Workspace receipts | No API surface | Workspace-to-Workspace only | Yes — admin and user controlled |
| Outlook `isReadReceiptRequested` | Yes (Graph property) | Outlook ecosystems | Yes — per-receipt prompt |
| **Open tracking + webhooks** | **Yes — structured events** | **Yes, any recipient** | **Only via image blocking** |

## Next steps

- [Email webhook events reference](https://cli.nylas.com/guides/email-webhook-events-reference) — payload shapes and retry rules for `message.opened` and friends
- [Test email webhooks locally](https://cli.nylas.com/guides/test-email-webhooks-locally) — receive tracking events on localhost before deploying
- [Personalize outbound email](https://cli.nylas.com/guides/personalize-outbound-email-cli) — the sending workflow that tracking labels were built for
- [Send email from the terminal](https://cli.nylas.com/guides/send-email-from-terminal) — every send flag including scheduling and templates
- [Full command reference](https://cli.nylas.com/docs/commands) — tracking flags and webhook subcommands documented