Отслеживание открытий и переходов

Два независимых переключателя, оба включены, если только их не выключили для адреса, с которого отправляется сообщение, или для All addresses. opens добавляет изображение 1×1; clicks переписывает ссылки в новой части тела. Цитируемая история под ответом — чужое сообщение, и её не трогают. Отправка указывает tracking: { opens, clicks }, чтобы решить за одно сообщение (в любую сторону, так что false — это способ для программы отказаться от того, что настроено на адресе), а опущенное поле откатывается к настройке адреса, с которого идёт отправка, затем к All addresses, а не к значению по умолчанию, которое этот API выбрал бы за рабочее пространство.

{    "from": "Acme Billing <[email protected]>",    "to": ["[email protected]"],    "subject": "Your September invoice",    "html": "<p>Invoice attached.</p>",    "tracking": { "opens": true, "clicks": true }  }

Переписывается не более 100 адресов назначения на сообщение, каждый по одному разу. Один и тот же URL, на который ссылаются картинка в шапке, кнопка и подвал, — это одна строка, потому что это один вопрос, заданный трижды. Сверх лимита остальные ссылки остаются ровно такими, как были написаны: неотслеживаемая ссылка всё равно работает, а сообщение, молча теряющее последние двести ссылок, — куда худший сбой, чем неполный отчёт.

Переписанные ссылки и пиксель по умолчанию указывают на хост API OpenEmail. Если у отправляющего домена есть собственный tracking-домен, у которого tracking.status равен active, новые письма с этого домена используют вместо него https://<tracking host>/t/..., а задаётся такой домен через PATCH /domains/{id}.

Это отдельный ресурс, а не несколько полей в /emails, из-за охвата: тот список содержит записи об отправках, а редактор, инструменты MCP и ассистент отправляют, не создавая их. Отчёт, построенный на нём, был бы отчётом о вашем трафике API, а не о почтовом ящике.

{    "object": "tracking",    "id": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",    "sendId": "msg_c5f21cc6bfec4e848caf905b",    "threadId": "thread_2f9b…",    "messageId": "<2598…@acme.com>",    "subject": "Your September invoice",    "from": "[email protected]",    "source": "api",    "sentAt": "2026-08-29T08:19:08.000Z",    "opens": true,    "clicks": true,    "opened": true,    "clicked": true,    "attributable": true,    "openCount": 3,    "openCountRaw": 7,    "clickCount": 1,    "clickCountRaw": 2,    "firstOpenAt": "2026-08-29T09:04:11.000Z",    "lastOpenAt": "2026-08-30T07:42:55.000Z",    "firstClickAt": "2026-08-29T09:05:02.000Z",    "lastClickAt": "2026-08-29T09:05:02.000Z",    "recipients": [      {        "email": "[email protected]",        "kind": "to",        "attributed": true,        "openCount": 3,        "clickCount": 1,        "firstOpenAt": "2026-08-29T09:04:11.000Z",        "lastOpenAt": "2026-08-30T07:42:55.000Z",        "firstClickAt": "2026-08-29T09:05:02.000Z",        "lastClickAt": "2026-08-29T09:05:02.000Z"      }    ],    "links": [      {        "id": "lnk_4f0a1c8d29b74e6fa3c05d17",        "url": "https://acme.com/invoices/42",        "label": "View invoice",        "clickCount": 1,        "clickCountRaw": 2      }    ]  }

opens и clicks — это то, что было ПРИМЕНЕНО к сообщению; opened и clicked — то, что произошло. openCount считает прочтения, а openCountRaw — загрузки. Разница, здесь равная четырём, — это сканеры и прокси приватности, сохраняемые для того, чтобы расхождение между журналом и итогом можно было изучить, а не оставить без объяснения. attributable — поле, которое нужно прочитать, прежде чем кого-либо называть: false означает, что прочтение пришлось на копию, ушедшую всему списку, и всякая фраза о конкретном получателе после этого — догадка.

source называет поверхность, с которой ушло сообщение: api — для отправки через этот API, composer — для всего, что отправило само приложение. Для второго вида sendId равен null — именно поэтому и существует tracking-id.

{    "object": "tracking_stats",    "tracked": 128,    "trackedForOpens": 128,    "trackedForClicks": 47,    "opened": 91,    "clicked": 34,    "openRate": 71.1,    "clickRate": 72.3,    "totalOpens": 240,    "totalClicks": 52,    "machineOpens": 173,    "medianTimeToOpenSeconds": 2714,    "byDay": [{ "day": "2026-08-27", "sent": 12, "opened": 9, "clicked": 3 }],    "topLinks": [{ "url": "https://acme.com/pricing", "label": "See pricing", "clickCount": 18 }],    "clients": [{ "client": "Gmail", "count": 96 }],    "countries": [{ "country": "GB", "count": 71 }]  }

Доли — это проценты от ОТСЛЕЖИВАЕМЫХ сообщений, а не от всей отправленной почты: у рабочего пространства, которое отслеживает одно сообщение из десяти, доля открытий считается по этим десяти, а деление на всё когда-либо отправленное падало бы каждый раз, когда кто-то отправляет неотслеживаемый ответ. Сообщение, открытое пять раз, — это ОДНО открытое сообщение. Доли считают сообщения, а итоги считают события, и смешение этих двух вещей — то, как публикуются доли открытий выше 100%.

{    "object": "list",    "data": [      {        "object": "open",        "id": "opn_1a7c…",        "trackedMessageId": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",        "recipient": "[email protected]",        "kind": "machine",        "counted": false,        "client": "Apple Mail Privacy Protection",        "device": "unknown",        "os": "macOS",        "country": "GB",        "region": "England",        "city": "London",        "createdAt": "2026-08-29T08:19:11.000Z"      }    ]  }

kind принимает значения human, proxy или machine, а counted говорит, повлияло ли событие на цифры. Машинные события исключаются, если не передать includeMachine=true, и это честное значение по умолчанию: их записывают потому, что их отбрасывание оставило бы необъяснимый пробел, а не потому, что они означают вовлечённость.

• —Apple Mail Privacy Protection загружает каждое изображение в каждом сообщении при доставке независимо от того, смотрит ли кто-нибудь. Это определяется по User-Agent и сети и записывается как machine, как и всё, что приходит в течение десяти секунд после отправки, потому что ничто из действий человека не происходит так быстро.
• —Прокси изображений Gmail — это proxy, а не machine: сообщение кто-то отобразил, поэтому открытие настоящее, тогда как устройство, клиент и местоположение узнать нельзя. Прокси ещё и кэширует, поэтому второе прочтение может вообще до нас не дойти. Цифры через Gmail — это нижняя граница, а не итог.
• —Две загрузки одной и той же копии в пределах тридцати секунд — это одно прочтение. Перерисовка панели предпросмотра или сообщение, вновь попавшее в область видимости при прокрутке, заново загружают изображение; настоящий второй визит час спустя по-прежнему засчитывается.
• —Чтобы назвать получателя, сообщение должно быть достаточно небольшим для пересборки под каждого: оценочный размер, умноженный на число получателей, должен укладываться в 8MB. Выше этого одно тело уходит всем, и каждое событие по нему остаётся без атрибуции.
• —Сообщение с переходами и без открытий точно было прочитано: изображения блокируют гораздо чаще, чем оставляют ссылки без нажатия. Читайте эти два счётчика по отдельности, а не складывайте их.
• —Запрос отслеживания переходов для тела без ссылок не записывает вообще ничего: ушедшие байты идентичны неотслеживаемой отправке, и строку, утверждающую обратное, было бы не с чем сверить. То же верно для сообщения, в котором нечего переписывать.
• —OpenEmail вырезает изображения 1×1 из писем, которые читают его собственные пользователи, включая отправляемый им самим пиксель, и сам записывает открытие, когда сообщение отображается с показом изображений. Такое событие имеет тип human и клиент OpenEmail. При скрытых изображениях не записывается ничего.

Засчитанное открытие вызывает email.opened, а засчитанный переход — email.clicked на каждом подписанном эндпоинте, и оба записываются в собственную историю событий сообщения, если оно прошло через этот API. Ни то, ни другое не срабатывает для сканера или прокси приватности. Их отправка заполнила бы журнал получателя ровно тем трафиком, который классификатор и существует, чтобы держать вне цифр.

Файл, ушедший ссылкой на скачивание, отчитывается так же. Засчитанное скачивание вызывает email.downloaded и попадает в ту же историю, и тот же классификатор держит вне её сканеры и генераторы превью ссылок, поэтому счётчик считает людей. Полезная нагрузка называет файл (shareId, fileId, filename, mimeType, sizeBytes, url) вместе с downloadCount, first и downloadedAt, рядом с полями клиента и местоположения, которые несёт переход. recipient всегда null, а attributed всегда false: ссылка на скачивание — это один URL для всех получателей сообщения, поэтому скачивание нельзя привязать к одному из них.

const report = await openemail.tracking.get('msg_c5f21cc6bfec…')const cold = await openemail.tracking.list({ days: 30, opened: false })const stats = await openemail.tracking.getStats({  days: 30,  offsetMinutes: -new Date().getTimezoneOffset(),})

Каждый вызов здесь — обычное чтение, и клиент повторяет каждый из них самостоятельно. get бросает OpenEmailApiError, у которого isNotFound равен true для сообщения, которое никогда не отслеживалось, — и именно это различие стоит сохранять в том, куда вы это передаёте.