Разберём два сценария: человек входит по одноразовому коду и получает подтверждение бронирования. Для первого соберём письмо и поле ввода, для второго — HTML, логотип, PDF-билет, разметку Gmail и календарный файл. По ходу объясним, что выполняет ваш сервер, что делает почтовый клиент и как проверить каждую часть.

Начните со своей задачи: письмо с кодом, подтверждение с вложениями, карточка бронирования Gmail, промоакция или событие в календаре. Ниже идут веб-поле и WebOTP, Android и iPhone. Это разные интеграции: добавление одной не включает остальные.

Обновлено 12 ноября 2026 года. Добавлены сквозной пример письма, сборка .eml без отправки, разбор полей Gmail и жизненного цикла календарного приглашения.

Копирование, автозаполнение и проверка — три разные задачи

Распознавание находит код в сообщении. Автозаполнение предлагает или переносит его в нужное поле. Серверная проверка решает, подтверждает ли этот код конкретное действие. Удобная кнопка не заменяет ни связи с попыткой входа, ни проверки срока действия.

Сам OTP — одноразовый код, а не обязательно «второй фактор». Код для подтверждения адреса, входа без пароля и дополнительной проверки после пароля может выглядеть одинаково. В интерфейсе нужно объяснять цель действия, а в архитектуре — различать эти сценарии.

Сообщение с кодом, системная подсказка, поле и серверная проверка — отдельные этапы
Рабочая модель: распознать код недостаточно, нужно сохранить связь с его назначением. Это схема процесса, а не скриншот конкретной ОС.

Что изменилось в Gmail — и чего это не обещает

В сентябре 2026 года профильные издания сообщили о кнопке копирования OTP в мобильном Gmail. Android Authority описывает кнопку прямо под темой письма во входящих. Наблюдения касаются Android и iOS. Это сообщение о развёртывании функции, а не опубликованный контракт для разработчиков.

Кнопка Copy code под темой письма Humble Bundle в списке входящих Gmail
Код можно скопировать, не открывая письмо. Голубая кнопка Copy code находится под темой во входящих. Цифры скрыты автором скриншота. Это наблюдение работы функции, а не элемент HTML-шаблона, который отправитель добавил в письмо. Источник: Hadlee Simons / Android Authority.

Поэтому в спецификации продукта нельзя обещать: «В Gmail у всех появится Copy code». Распознавание зависит от письма и доступности функции. Не следует переносить наблюдение о списке писем на push-уведомление, веб-версию Gmail или любой другой почтовый клиент. Для собственного сервиса достаточно сделать письмо понятным без специальной кнопки.

Предлагаемый шаблон письма: тема «Код входа в Example», один хорошо заметный код, назначение действия, срок действия и пояснение, что делать, если человек не запрашивал вход. Рядом не нужны похожие шестизначные номера заказа, лишние рекламные блоки или код только в картинке. Добавьте текстовую часть MIME-письма. Реальный результат проверяйте в используемых клиентских приложениях. Это рекомендации по ясности, а не документированный способ принудительно включить кнопку Gmail.

Text
Код входа в Example

482913

Вы запросили вход в аккаунт на example.com.
Код действует 5 минут. Не сообщайте его другим людям.
Если это были не вы, не подтверждайте вход.

Пример иллюстративный: пять минут — выбранная политика сервиса, а не общий лимит Gmail. В реальном продукте срок письма должен совпадать с серверной политикой.

Summary Cards, Email Markup и OTP нельзя объединять в один API

Gmail умеет показывать и другие полезные сведения. Справка Google о Summary Cards перечисляет отслеживание заказов, события, поездки, счета и предложения. Показ зависит в том числе от настроек умных функций и наличия достаточных данных в письме. Сводная карточка — часть интерфейса почтового клиента.

Четыре примера Gmail: доставка, билет на событие, счёт и перелёт с карточками над письмами
Карточка расположена над содержимым письма. Слева направо: доставка, событие с билетом, счёт и перелёт. Посмотрите на второй экран: дата, место и View ticket собраны отдельно от оформления письма ниже. Официальная иллюстрация Google из публикации 2024 года; конкретный интерфейс может меняться. Источник: Google.
МеханизмЧто делаетЧто может контролировать отправитель
Распознавание OTPМожет выделить код и предложить копированиеПонятность письма. Публичного переключателя Copy code не подтверждено
Summary CardsСводит сведения о заказах, поездках и других событияхКорректные и согласованные данные в письмах
Email Markup / HighlightsОписывает поддерживаемые сущности и действияРазметку, аутентификацию отправителя и процедуру допуска
Gmail APIДаёт разрешённый доступ к данным почтового ящикаOAuth-интеграцию своего приложения и обработку разрешённых данных

Gmail Email Markup использует Schema.org и поддерживаемые форматы JSON-LD и Microdata для сущностей вроде заказа, доставки и бронирования. Это не способ объявить произвольный объект OTP и получить гарантированное автозаполнение. Для запуска размеченных писем у Google есть регистрация отправителя и требования к качеству и аутентификации писем. Валидный JSON сам по себе не гарантирует специальный интерфейс у адресата.

В документированном ресурсе Gmail API Message поле snippet — короткий фрагмент текста. Его нельзя трактовать как готовый OTP или результат Summary Cards. Отдельный публичный метод получения распознанного Gmail кода или карточки в проверенной документации не найден. Классификационные метки Workspace также не означают, что API отдаёт OTP.

Собираем понятное письмо: от данных до HTML

Представим мастер-класс по керамике: Alex забронировал место на 21 ноября, с 10:00 до 12:00 по Праге. Письмо должно сразу ответить на четыре вопроса: подтверждено ли место, когда приходить, куда идти и где билет. Даже если Gmail не покажет карточку, а картинки не загрузятся, эти ответы должны остаться.

Содержание, которое увидит получатель в демонстрационном письме:

Booking WS-1042 confirmed

Hello, Alex Morgan.

Ceramics workshop
21 November 2026, 10:00–12:00 (Europe/Prague)
Example Studio
Example Street 12, 110 00 Prague, Prague, CZ

Your PDF ticket is attached.

Все имена, адреса, домены и бронирование в примерах вымышлены. Код письма на английском, чтобы один и тот же пример можно было повторить в каждой языковой версии статьи. Это Node.js-модуль для проекта с уже установленным Nodemailer; он создаёт локальный preview.eml, никому ничего не отправляя. Сохраните следующие два блока по порядку в email-demo.mjs.

JavaScript
import nodemailer from "nodemailer";
import { readFile, writeFile } from "node:fs/promises";

const booking = {
  id: "WS-1042", name: "Alex Morgan", event: "Ceramics workshop",
  start: "2026-11-21T10:00:00+01:00", end: "2026-11-21T12:00:00+01:00",
  when: "21 November 2026, 10:00–12:00 (Europe/Prague)",
  venue: "Example Studio", street: "Example Street 12",
  city: "Prague", region: "Prague", postalCode: "110 00", country: "CZ"
};
const escapeHtml = value => String(value).replace(/[&<>"']/g,
  c => ({"&":"&amp;", "<":"&lt;", ">":"&gt;", '"':"&quot;", "'":"&#39;"})[c]);
const address = `${booking.street}, ${booking.postalCode} ${booking.city}, ${booking.region}, ${booking.country}`;
const text = `Booking ${booking.id} confirmed\n\nHello, ${booking.name}.\n${booking.event}\n${booking.when}\n${booking.venue}: ${address}\nYour PDF ticket is attached.`;
let html = `<!doctype html><html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
</head><body style="margin:0;padding:24px;background:#ffffff;color:#202020;font-family:Arial,sans-serif">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td>
<img src="cid:brand-logo@example.com" width="160" height="48" alt="Example Studio" style="display:block;border:0">
<h1 style="font-size:24px;line-height:32px">Booking ${escapeHtml(booking.id)} confirmed</h1>
<p>Hello, ${escapeHtml(booking.name)}.</p>
<p><strong>${escapeHtml(booking.event)}</strong><br>${escapeHtml(booking.when)}</p>
<p>${escapeHtml(booking.venue)}<br>${escapeHtml(address)}</p>
<p>Your PDF ticket is attached.</p>
</td></tr></table></body></html>`;

booking — единый источник данных для текста, HTML, Gmail и календаря. В рабочем сервисе это проверенное бронирование из базы; строку when формируют из даты и часового пояса, а не поддерживают вручную. escapeHtml превращает символы в имени вроде < в текст, чтобы имя не стало тегом. text — самостоятельная читаемая версия письма, которую клиент может выбрать вместо HTML.

ЭлементЗачем он здесьЧто проверять
h1, p, br, strong, a, ul, liОбычный текст, иерархия и ссылкиСмысл остаётся без стилей; действие открывается обычной HTTPS-ссылкой.
table, tr, tdПредсказуемая раскладкаУ таблиц для оформления — role="presentation". Таблицы с данными сохраняют семантику.
imgЛоготип или иллюстрацияЗаданы реальные пропорции, размеры и alt. Дата, цена и код не спрятаны в изображении.
Inline CSSКритичные отступы, цвет и шрифтОсновное содержание не зависит от внешнего CSS, flex/grid или фонового изображения.
script, iframe, formНе использовать для обычного интерактивного письмаJSON-LD ниже — блок данных специального назначения, а не разрешение выполнять JavaScript.

Это консервативная основа, а не универсальная сертификация тегов. Например, Gmail поддерживает часть <style> и media queries, но это не доказывает поддержку классическим Outlook. Справочник Gmail полезен для проверки конкретного CSS-свойства. Проверка результата — полученное письмо с отключёнными картинками, на узком экране и в тёмной теме.

Добавляем логотип и PDF: почему одного HTML недостаточно

В HTML выше cid:brand-logo@example.com — ссылка на часть самого письма. Nodemailer получает PNG с точно таким же cid и связывает их. PDF остаётся отдельным скачиваемым файлом. Добавьте второй блок; запустите node email-demo.mjs ./logo.png ./ticket.pdf, передав свой PNG размером 160×48 и тестовый PDF без персональных данных.

JavaScript
const [logoPath, ticketPath] = process.argv.slice(2);
if (!logoPath || !ticketPath) throw new Error("Pass a PNG logo and a PDF ticket");
const [logo, ticket] = await Promise.all([readFile(logoPath), readFile(ticketPath)]);
if (!logo.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) {
  throw new Error("Logo is not a PNG");
}
if (ticket.subarray(0, 5).toString() !== "%PDF-") throw new Error("Ticket is not a PDF");
const message = {
  from: "Example Studio <booking@example.com>", to: "alex@example.com",
  subject: `Booking ${booking.id} confirmed`, text, html,
  attachments: [
    { filename: "logo.png", content: logo, contentType: "image/png",
      cid: "brand-logo@example.com", contentDisposition: "inline" },
    { filename: `ticket-${booking.id}.pdf`, content: ticket,
      contentType: "application/pdf", contentDisposition: "attachment" }
  ]
};
const previewTransport = nodemailer.createTransport({
  streamTransport: true, buffer: true, newline: "windows"
});
const result = await previewTransport.sendMail(message);
await writeFile("preview.eml", result.message);

Откройте preview.eml в почтовом клиенте как локальный файл: должны быть видны текст, логотип и PDF-вложение. Это проверка собранного сообщения, ещё не проверка доставки. Проверка сигнатур в примере ловит перепутанный тип файла, но не заменяет проверку содержимого PDF и соответствия билета получателю. Если чтение файла упало, письмо не собирается: фраза «билет приложен» не отправится без билета.

MIME — способ упаковать несколько частей в одно письмо. Одна подходящая структура выглядит так; библиотека создаёт разделители и кодирование сама:

Text
multipart/mixed
├── multipart/alternative
│   ├── text/plain; charset=utf-8
│   └── multipart/related
│       ├── text/html; charset=utf-8
│       └── image/png; Content-ID: <brand-logo@example.com>
└── application/pdf; filename=ticket-WS-1042.pdf

alternative предлагает две версии одного содержания; related связывает HTML с его картинкой; mixed добавляет самостоятельный документ. Менять расширение на .pdf недостаточно: важны байты и Content-Type. Считайте размер готового сообщения, поскольку base64 увеличивает размер файла примерно на треть. Для массовой отправки собирайте персональный билет для каждого получателя, а не общий BCC с чужими документами.

Здесь логотип находится внутри тела письма. Можно заменить CID публичной стабильной HTTPS-картинкой, если её публикация допустима, но клиент может блокировать и внешние, и встроенные изображения. Логотип рядом с промоакцией задаётся отдельным полем ниже. Аватар рядом с отправителем через BIMI относится к настройке домена и требованиям почтового провайдера; PNG в HTML не включает BIMI. Не публикуйте приватный PDF ради удобной ссылки. Параметры вложений Nodemailer и локальная сборка через stream transport описывают используемый здесь API.

Gmail-карточка бронирования: какие данные передать и куда

Получатель читает «мастер-класс, 21 ноября, 10:00». Разметка передаёт те же факты машинно: это подтверждённое бронирование WS-1042, его владелец — Alex, событие проходит по указанному адресу. Gmail может использовать их в поддерживаемом интерфейсе бронирований. Это не HTML-карточка, которую вы рисуете сами, и не команда автоматически добавить событие в календарь.

Карточка бронирования ресторана в Gmail до и после обновления: время, адрес и кнопки действий
Что Gmail выделяет из подтверждения. Справа крупнее показаны дата и время, ниже — место и действия Invite others, Call, Modify booking. Сравнение Google 2024 года показывает бронирование ресторана: это иллюстрация интерфейса, не результат запуска нашего EventReservation. Для ресторана используется другой тип схемы. Источник: Google.

Вставьте следующий блок между первым и вторым блоком примера, до создания message. Он добавит JSON-LD в <head> письма; посетитель не должен видеть JSON как текст. Изменять JSON-LD сайта или передавать его отдельным JSON-файлом во вложении для этого не нужно.

JavaScript
function emailJsonLd(data) {
  const json = JSON.stringify(data);
  if (json === undefined) throw new Error("Missing structured data");
  return '<script type="application/ld+json">' + json
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e")
    .replace(/&/g, "\\u0026")
    .replace(/\u2028/g, "\\u2028")
    .replace(/\u2029/g, "\\u2029") + '</script>';
}
const reservation = {
  "@context": "http://schema.org", "@type": "EventReservation",
  reservationNumber: booking.id,
  reservationStatus: "http://schema.org/ReservationConfirmed",
  underName: { "@type": "Person", name: booking.name },
  reservationFor: {
    "@type": "Event", name: booking.event,
    startDate: booking.start, endDate: booking.end,
    location: {
      "@type": "Place", name: booking.venue,
      address: {
        "@type": "PostalAddress", streetAddress: booking.street,
        addressLocality: booking.city, addressRegion: booking.region,
        postalCode: booking.postalCode, addressCountry: booking.country
      }
    }
  }
};
html = html.replace("</head>", emailJsonLd(reservation) + "</head>");

reservationNumber связывает письмо с бронированием, underName называет владельца, reservationFor описывает событие. +01:00 фиксирует смещение для этой ноябрьской даты: без него «10:00» неоднозначно. В примере указан полный адрес, потому что Google требует его для этого типа. Если в базе есть только название города, сначала нужно получить точный адрес площадки. Заполнять обязательные поля догадками нельзя. Контракт EventReservation определяет состав полей.

Сериализация нужна не только ради удобства. Название события может содержать кавычки или буквальный </script>. JSON.stringify правильно оформляет JSON, а замена < на \u003c не даёт значению закрыть HTML-блок. После разбора JSON исходное название восстановится. &quot; здесь не замена кавычке JSON: это испортит данные. Формат блока описан в документации JSON-LD для писем.

Проверка идёт в четыре шага: разберите JSON из итогового HTML; сравните номер, владельца, время и адрес с видимым письмом; проверьте HTML через Email Markup Tester; затем проверьте непосредственно полученное письмо. Google разрешает самотестирование при совпадении аккаунта отправителя и получателя, но SPF или DKIM всё равно требуется. Для отправки пользователям отдельно выполняется процедура регистрации. Поэтому успешный локальный .eml не означает, что карточка уже заработала у клиентов. Тестирование схем и регистрация — следующие этапы после сборки.

Promotions: как описать скидку, не перепутав её с OTP

Теперь другой сценарий: человек ещё не купил мастер-класс. Вы отправляете акцию «60 € → 45 €, код CLAY15, до 20 ноября». Аннотация позволяет передать изображение, предложение и срок для вкладки Promotions. Эти же условия должны быть написаны обычным текстом в промописьме; подписка и отписка остаются частью вашего рассылочного процесса.

Строка письма во вкладке Promotions: отметка 20% Off и промокод 20TODAY
DiscountOffer: короткая отметка под темой. Здесь видны скидка 20% и код 20TODAY. Это промокод для покупки, не код входа; открывать письмо, чтобы увидеть предложение, не нужно. Источник: Google Developers.
Промописьмо Gmail с логотипом Motto, скидкой, кодом и большим изображением товара
PromotionCard: предложение становится наглядным. Под отправителем и темой появляется изображение товара с подписью. Оно берётся из публичного URL в аннотации; это превью во входящих, а не картинка, вставленная в тело письма. Источник: Google Developers.

Следующий объект относится к отдельному промописьму, а не к подтверждению выше. Используйте ту же функцию emailJsonLd. Все URL на example.com — обозначения для примера: замените их своими проверенными публичными HTTPS-ресурсами до отправки.

JavaScript
const promotion = [
  { "@context": "http://schema.org/", "@type": "Organization",
    logo: "https://example.com/assets/logo.png" },
  { "@context": "http://schema.org/", "@type": "DiscountOffer",
    description: "Save €15 on the ceramics workshop", discountCode: "CLAY15",
    availabilityStarts: "2026-11-12T09:00:00+01:00",
    availabilityEnds: "2026-11-20T23:59:00+01:00" },
  { "@context": "http://schema.org/", "@type": "PromotionCard",
    image: "https://example.com/assets/workshop.jpg",
    url: "https://example.com/offers/ceramics",
    headline: "Ceramics workshop", price: "60", priceCurrency: "EUR",
    discountValue: "15" }
];
// In a separate promotional email, before building its message object:
html = html.replace("</head>", emailJsonLd(promotion) + "</head>");

Здесь price: "60" — исходная цена, а discountValue: "15" — сумма, которую вычитают: итог 45 €, не скидка 15%. CLAY15 должен реально приниматься вашим checkout. availabilityEnds должен совпадать с окончанием акции на сервере. Для PromotionCard нужны картинка PNG/JPEG и целевая ссылка; у картинки — поддерживаемые пропорции 4:5, 1:1 или 1.91:1. CID-картинку из письма сюда не подставляют: сервису нужен доступный URL. Даже корректная аннотация не управляет сортировкой во вкладки и не гарантирует показ. Механизм Promotions и значения полей описывают именно это представление.

Карусель Promotions с несколькими товарами, названиями и исходными и сниженными ценами
Несколько PromotionCard — карусель товаров. В одном превью можно показать несколько предложений, у каждого свои картинка, название и цена. Это отдельный вариант аннотации; в примере мастер-класса выше достаточно одной карточки. Источник: Google Developers.

event.ics: сначала выберите импорт или приглашение

Для купленного мастер-класса обычно достаточно кнопки «Добавить в календарь» или файла, который человек импортирует. Это копия события у получателя. Если время позже изменится в вашей базе, такая копия не обязана обновиться. Если нужны ответы «Приму / Отклоню», перенос и отмена, нужен полноценный обмен приглашениями и обработка ответов, а не только другое имя файла.

Так выглядит минимальный файл для ручного импорта нашего события. DTSTART:20261121T090000Z — 09:00 UTC, то есть 10:00 в Праге в эту дату. DTEND — конец события. UID задаёт его постоянную идентичность. DTSTAMP — время формирования данных, не время начала мастер-класса.

Text
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Studio//Booking//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:booking-WS-1042@example.com
DTSTAMP:20261112T120000Z
DTSTART:20261121T090000Z
DTEND:20261121T110000Z
SUMMARY:Ceramics workshop
LOCATION:Example Studio\, Example Street 12\, Prague
DESCRIPTION:Booking WS-1042\nBring your PDF ticket.
END:VEVENT
END:VCALENDAR

В файле нужны окончания строк CRLF и завершающий CRLF. Запятые, точки с запятой, обратные косые черты и переносы внутри текстовых значений экранируются. Длинные строки переносятся по байтам UTF-8, поэтому украинский текст нельзя обрезать обычным slice(0, 75). Добавьте этот код после создания message, до вызова previewTransport.sendMail:

JavaScript
const escapeIcsText = value => String(value).replace(/\\/g, "\\\\")
  .replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r\n|\r|\n/g, "\\n");
function foldIcsLine(line) {
  let result = "", bytes = 0;
  for (const character of line) {
    const length = Buffer.byteLength(character, "utf8");
    if (bytes + length > 75) { result += "\r\n "; bytes = 1; }
    result += character; bytes += length;
  }
  return result;
}
const utc = value => new Date(value).toISOString()
  .replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
const calendar = [
  "BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//Example Studio//Booking//EN",
  "CALSCALE:GREGORIAN", "BEGIN:VEVENT", `UID:booking-${booking.id}@example.com`,
  `DTSTAMP:${utc(new Date())}`, `DTSTART:${utc(booking.start)}`, `DTEND:${utc(booking.end)}`,
  `SUMMARY:${escapeIcsText(booking.event)}`,
  `LOCATION:${escapeIcsText(booking.venue + ", " + address)}`,
  `DESCRIPTION:${escapeIcsText("Booking " + booking.id + "\nBring your PDF ticket.")}`,
  "END:VEVENT", "END:VCALENDAR"
].map(foldIcsLine).join("\r\n") + "\r\n";
message.attachments.push({ filename: "event.ics", content: Buffer.from(calendar),
  contentType: "text/calendar; charset=utf-8", contentDisposition: "attachment" });

Префикс Z означает UTC. Для реального бронирования храните IANA-зону, например Europe/Prague, и вычисляйте смещение для даты события: летом здесь будет +02:00, а не +01:00. Не используйте часовой пояс сервера. Проверяйте, что конец позже начала; несуществующее время при переходе на летний режим требует явного решения. Для события на весь день используют VALUE=DATE; окончание 22 ноября означает, что последнее включённое число — 21 ноября. Правила данных и строк задаёт iCalendar.

Для настоящего приглашения к тем же данным события добавляются поля ниже. Это только изменения, а не полный файл; многоточие обозначает остальные строки. Организатор и адресат должны быть реальными участниками обмена. PARTSTAT=NEEDS-ACTION означает «ответа ещё нет»; ставить ACCEPTED за человека нельзя.

Text
METHOD:REQUEST
...
UID:booking-WS-1042@example.com
SEQUENCE:0
ORGANIZER:mailto:events@example.com
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:alex@example.com

Внутри календаря нужен METHOD:REQUEST, а у MIME-части — Content-Type: text/calendar; charset=utf-8; method=REQUEST. В Nodemailer для такого письма есть icalEvent: { method: "REQUEST", content: requestCalendar }; этот путь используйте вместо обычного календарного вложения и держите приглашение простым, без дополнительных PDF и картинок, мешающих некоторым клиентам распознать его. Сам requestCalendar должен содержать полный корректный календарь. API Nodemailer упаковывает данные, но не создаёт систему планирования.

ДействиеЧто отправитьЧто хранить на сервере
Первое приглашениеREQUEST, UID booking-WS-1042@example.com, SEQUENCE:0Организатор, участник, время и текущая версия.
Перенос на 11:00REQUEST, тот же UID, SEQUENCE:1, новые DTSTART/DTEND и DTSTAMPВерсию увеличивают при изменении; повтор доставки не создаёт новую версию.
Отмена после переносаCANCEL, тот же UID, SEQUENCE:2, STATUS:CANCELLEDОтмену и адресатов; MIME method тоже CANCEL.
Ответ участникаREPLY, тот же UID, соответствующая версия и PARTSTAT участникаПроверить отправителя и участника, актуальность события; затем обновить статус ответа.

Соответствие MIME-метода содержимому файла описывает iMIP, RFC 6047; переносы, отмены и ответы — iTIP, RFC 5546. Не доверяйте присланному ATTENDEE как доказательству личности. Даже с постоянным UID нужно отдельно проверить повторный импорт, перенос и отмену в целевых календарях: поведение клиента не следует из одного успешного разбора файла.

Как понять, где сломалось письмо

СимптомПроверкаИсправление
Нет логотипаВ исходнике письма найти src="cid:…" и соответствующий Content-ID. Затем включить картинки.Исправить несовпадение CID или упаковку related; сохранить текстовый бренд и alt.
Нет билета, но письмо обещает вложениеПроверить генерацию PDF и application/pdf в полученном MIME.Собирать сообщение после успешной генерации; не отправлять ложное подтверждение вложения.
Нет Gmail-карточкиПроверить сохранность JSON-LD после провайдера, обязательные поля и допуск отправителя.Исправить конкретный слой; не пытаться лечить это размером шрифта.
Событие на час раньшеСравнить исходную дату, IANA-зону, смещение и DTSTART.Вычислять UTC для даты экскурсии; согласовать HTML, текст и ICS.
При переносе появился дубльСравнить UID первого письма и обновления.Хранить UID; обновлять версию события, а не генерировать новую идентичность.

Сначала проверьте локальный .eml. Затем разрешённую тестовую отправку через рабочий провайдер: он может изменить HTML, ссылки или MIME. В Gmail, Apple Mail и используемых версиях Outlook проверьте обычный вид, тёмную тему, отключённые картинки, скачивание PDF и импорт ICS. Для RSVP дополнительно проведите полный цикл: приглашение → ответ → перенос → отмена. Записывайте клиент, версию и результат, а не одно общее «email работает».

Что выбрать для своего продукта

СценарийОсновной путьГраница возможностей
Сайт, свой SMS-отправительСемантика поля + доменная привязка. WebOTP там, где поддерживаетсяНе чтение всех SMS и не доступ к письмам
Android, можно менять SMSSMS Retriever APIGoogle Play services, формат сообщения и хеш приложения
Android, нельзя добавить хешSMS User Consent API, если сценарий соответствует условиямСогласие на одно сообщение, ограничения отбора и времени ожидания
iPhone-приложениеПоле oneTimeCode и системный AutoFillРаспознаванием и показом подсказки управляет ОС
Код приходит по emailПонятное письмо + корректное поле + доступные системные подсказкиWebOTP не является API чтения email
Помощник для чужих сайтов и приложенийРазрешённые платформенные интеграции с проверкой назначенияОтдельный продукт с доступом к чувствительным данным

Таблица описывает направления интеграции, а не гарантии по бренду телефона. Например, SMS Retriever относится к Google Play services: само наличие Android на устройстве не доказывает доступность этого механизма. Для устройств без нужных сервисов сначала нужно проверить официально поддерживаемый путь конкретной платформы.

Сайт: сначала правильное поле, затем WebOTP

Для числового кода используйте текстовое поле с цифровой клавиатурой. type="number" не подходит: код — идентификатор, а не число для вычислений. Начальные нули должны сохраняться. Рекомендации web.dev по OTP-формам объясняют сочетание inputmode и autocomplete="one-time-code".

HTML
<form id="verify-form" action="/auth/verify" method="post">
  <label for="otp">Код из сообщения</label>
  <p id="otp-hint">Введите 6 цифр. Начальные нули важны.</p>
  <input id="otp" name="code" type="text"
    inputmode="numeric" autocomplete="one-time-code"
    pattern="[0-9]{6}" maxlength="6" required
    aria-describedby="otp-hint otp-status">
  <p id="otp-status" role="status"></p>
  <button type="submit">Подтвердить</button>
</form>

Шесть цифр здесь — явный контракт примера. Для буквенно-цифровых кодов потребуется другое ограничение и другая клавиатура. Маршрут /auth/verify условный: реализация сервера, защита запроса и привязка к попытке входа в этот фрагмент не включены.

Один настоящий input обычно проще для вставки, редактирования, AutoFill и скринридера, чем шесть независимых полей. Если дизайн требует шесть ячеек, это не отменяет полноценного ввода всего кода, корректного порядка фокуса и доступного имени. Не запрещайте вставку и не заставляйте перепечатывать цифры.

WebOTP в документации Chrome получает специально оформленное SMS, связанное с доменом. Механизм требует безопасного контекста и поддержки браузера. Safari может предлагать системный AutoFill для подходящих сообщений, не реализуя тот же JavaScript API. Поэтому проверяйте возможность, а не название ОС.

Text
Код для входа в Example: 004291

@example.com #004291

В последней строке — точный домен без схемы и пути и код с префиксом #. Для встраиваемых фреймов есть отдельные правила формата и Permissions Policy. Их нужно сверить с документацией WebOTP. Этот пример относится к обычной странице верхнего уровня.

JavaScript
const form = document.querySelector("#verify-form");
const input = document.querySelector("#otp");
const status = document.querySelector("#otp-status");

if (form && input && status && "OTPCredential" in window) {
  const controller = new AbortController();
  const stop = () => controller.abort();
  form.addEventListener("submit", stop, { once: true });
  input.addEventListener("input", stop, { once: true });
  window.addEventListener("pagehide", stop, { once: true });
  const timer = window.setTimeout(stop, 60_000);

  navigator.credentials.get({
    otp: { transport: ["sms"] },
    signal: controller.signal
  }).then(credential => {
    if (!controller.signal.aborted && credential?.code && !input.value) {
      input.value = credential.code;
      input.dispatchEvent(new Event("input", { bubbles: true }));
      status.textContent = "Код подставлен. Проверьте и подтвердите вход.";
    }
  }).catch(error => {
    if (error.name !== "AbortError") {
      status.textContent = "Введите код из сообщения вручную.";
    }
  }).finally(() => {
    window.clearTimeout(timer);
    form.removeEventListener("submit", stop);
    input.removeEventListener("input", stop);
    window.removeEventListener("pagehide", stop);
  });
}

Слушатель запускают до отправки ожидаемого SMS. В реальном потоке старт нужно согласовать с запросом к серверу. Пример отменяет ожидание при ручном вводе, отправке формы и уходе со страницы, не перезаписывает введённый код и не отправляет форму сам. Ожидание 60 секунд — настройка интерфейса, не срок жизни OTP. При отсутствии API, отказе пользователя или тайм-ауте доступен тот же ручной ввод. В компоненте SPA дополнительно отменяйте ожидание при размонтировании.

Android: Retriever, User Consent и AutofillService решают разные задачи

Практическая последовательность для Retriever: сервер создаёт попытку подтверждения; приложение запускает ожидание; после успешного старта запрашивает отправку SMS; сервер отправляет текст с кодом и хешем приложения; receiver получает результат; приложение передаёт код вместе с попыткой на сервер. На каждом шаге есть собственная ошибка. Например, неправильный release-хеш ломает получение сообщения приложением, но не доставку SMS на телефон — поэтому «SMS пришло» ещё не доказывает работу Retriever.

SMS Retriever API связывает сообщение с приложением через хеш. Команда согласует формат SMS с сервером, запускает ожидание до отправки и проверяет сообщение после получения. Это позволяет реализовать подтверждение без общего разрешения на чтение SMS.

Клиентские точки входа — SmsRetriever.getClient(context).startSmsRetriever() и startSmsUserConsent(senderAddress). Справочник SmsRetrieverClient описывает SMS_RETRIEVED_ACTION, статусы и защиту receiver разрешением SEND_PERMISSION. Успешный запуск ожидания ещё не означает, что сообщение получено. Согласие разбирают отдельно от результата доставки.

Внедрение требует зависимости Google Play services, корректного receiver, обработки успеха и тайм-аута. Хеш должен соответствовать идентификатору пакета и сертификату подписи: рабочая debug-сборка не доказывает работоспособность релиза из магазина. Передавайте полученный код в серверную проверку конкретной попытки, а не считайте получение SMS успешным входом.

Если добавить хеш нельзя, изучите SMS User Consent API. Пользователь разрешает передать приложению текст одного сообщения. Это существенное дополнение к упрощённому правилу «чужое SMS — только системная подсказка», но не разрешение собирать произвольные сообщения.

Официальный пример Google: системный запрос согласия передать приложению одно SMS с кодом
Пример интерфейса из документации Google по SMS User Consent. Согласие относится к одному сообщению, а не ко всей истории SMS.

У User Consent есть условия отбора: ожидается буквенно-цифровой код длиной 4–10 символов хотя бы с одной цифрой. Отправитель не должен находиться в контактах. Документация описывает пятиминутное окно ожидания. Это параметры работы API, а не обязательные длина и срок жизни вашего OTP. Отмена согласия должна оставлять возможность ввести код вручную.

AutofillService — роль отдельного поставщика автозаполнения, например менеджера паролей, который пользователь включает в системе. Для обычного приложения, принимающего собственный код, это обычно другой уровень задачи. SMS Code Autofill API также относится к сценарию поставщика автозаполнения. Его нельзя считать разрешением для любого приложения перехватывать SMS.

Чтение уведомлений — ненадёжная основа для универсального сборщика кодов. В Android 15 содержимое уведомлений с обнаруженным OTP скрывается от недоверенных NotificationListenerService. Наличие пользовательского доступа к уведомлениям не отменяет это ограничение. Не проектируйте продукт вокруг обхода защиты.

iPhone: пометьте поле, распознавание оставьте системе

Email-коды умеют подставляться и без уведомлений сторонних приложений. В перечне функций iOS 17 Apple описывает AutoFill из Mail в Safari. Один и тот же ящик, открытый в Apple Mail и в приложении Gmail, не означает одинаковый путь распознавания. Для своего письма проверяйте конкретный клиент, настройки и поле назначения.

В официальном перечне функций iOS 26 Apple указывает Verification Code AutoFill from Notifications: коды могут подставляться из уведомлений приложений. Это системная возможность, а не API, позволяющий вашему приложению прочитать уведомления Gmail или любого мессенджера.

Для UIKit применяется UITextContentType.oneTimeCode, в SwiftUI — соответствующий модификатор поля:

Swift
TextField("Код подтверждения", text: $code)
    .textContentType(.oneTimeCode)
    .keyboardType(.numberPad)

Параметр клавиатуры подходит только числовому коду. Доступность нужной подсказки зависит от распознанного сообщения, настроек и состояния устройства. Для SMS своего сервиса Apple описывает доменную привязку. Для приложения также учитываются связанные домены. Веб-поле с autocomplete="one-time-code" и нативное oneTimeCode выражают назначение ввода, но не гарантируют подсказку из каждого источника.

Отдельно проверяйте настройки уведомлений и скрытых превью. Если код не попал в доступное системе содержимое, нельзя рассчитывать, что функция его «достанет» из закрытого ящика. У приложения не появляется право читать соседние уведомления. TOTP из менеджера паролей — ещё один отдельный источник, его не следует смешивать с кодом, доставленным письмом.

Универсальный помощник — отдельный продукт

Улучшить свой checkout и построить помощника для любых сайтов — разные по масштабу проекты. Во втором случае сначала нужно определить, где он работает: расширение браузера, выбранный поставщик автозаполнения Android, почтовый клиент или разрешённое расширение платформы. Сайт не может сам превратиться в системный менеджер кодов на всём телефоне.

Gmail API с OAuth может дать приложению разрешённый доступ к содержимому писем. Но это доступ к данным ящика, а не узкий запрос «выдай ожидаемый код». В списке OAuth scopes Gmail чтение почты относится к restricted scopes. Требования к проверке приложения и, в применимых случаях, оценке безопасности нужно изучить до реализации. Для собственного OTP-экрана запрашивать доступ ко всему ящику обычно несоразмерно задаче.

Для другого почтового провайдера требуется его поддерживаемая интеграция и согласие пользователя. Нельзя обещать одинаковую работу с любым клиентом лишь потому, что оба показывают push. Публичного универсального интерфейса «все OTP со всех каналов» в рассмотренных платформах нет.

Если такой продукт всё же оправдан, связывайте найденное сообщение с конкретным запросом: аккаунтом, точным доменом или проверенной идентичностью приложения, назначением действия и временным окном. Совпадение имени отправителя, текста темы и последних шести цифр недостаточно. При неоднозначности не угадывайте: покажите контекст человеку или откажитесь от автоматического переноса. Подтверждение адреса, вход и перевод средств нельзя объединять только по одинаковому формату кода.

Что должно происходить после подстановки

Пример: пользователь запросил код A, нажал «Отправить ещё раз» и получил B. Если политика сервиса отменяет предыдущий код, A должен отклоняться, даже когда он пришёл позже и AutoFill подставил его первым. Сервер связывает проверку с идентификатором попытки, адресатом и назначением; проверяет срок, лимит попыток и одноразовое использование. Проверку кода и пометку «использован» выполняют атомарно, иначе два параллельных запроса могут принять один OTP дважды. Подстановка в поле меняет только интерфейс — сессию создаёт сервер после успешной проверки.

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

Не записывайте OTP, содержимое письма или SMS в аналитику, консоль и тексты ошибок. Измерять можно попытки, задержку доставки, частоту повторной отправки и результат проверки без самих секретов. Различайте «код предложен», «поле заполнено» и «сервер подтвердил действие»: это разные события, а не один показатель успешного входа.

Интерфейс должен сохранять введённое при временной ошибке сети, объяснять истечение срока, позволять исправить адрес или номер и повторно отправить сообщение после понятного ограничения. Не очищайте поле при каждой неудаче и не объявляйте человеку «неверный код», если запрос вообще не дошёл до сервера. Автоматическая подстановка не должна перекрывать ручную вставку или неожиданно менять уже введённые цифры.

Проверка перед выпуском

СитуацияОжидаемый результат
Код начинается с нулейНули сохранены при вводе, вставке и отправке
Сообщение пришло до запуска ожиданияПользователь может ввести код. Интерфейс не зависает
Другой домен, аккаунт или назначениеАвтоматическая передача не производится по одному совпадению цифр
Пользователь отказал в доступеТот же сценарий можно завершить вручную
Повторная отправка и старый кодРаботает явно заданная серверная политика
Ручной ввод во время ожиданияПоздний AutoFill не перезаписывает введённое
Отказ сети, истечение срока, повторное использованиеПонятные разные состояния и корректная серверная проверка
Клавиатура, скринридер, увеличенный текстПоле имеет имя, ошибки связаны с ним, фокус не скачет
Release-подпись Android и целевые устройстваПроверена реальная интеграция, а не только debug-сборка

Матрица нужна по каналам и реализациям: SMS своего сервиса, email, поддерживаемый WebOTP-браузер, Safari, целевые Android с нужными сервисами, iPhone с подходящей версией ОС. Отдельно проверяются несколько одновременных попыток, изменение аккаунта, уход со страницы и отсутствие уведомления. Утверждение «работает на iOS» не заменяет запись версии, настроек и проверенного сценария.

Скилл для разработки email-писем

По результатам этого исследования мы создали отдельный скилл Email Development для Codex и Claude Code. Он помогает создавать и улучшать письма: от темы и текстовой версии до HTML-шаблона, OTP, структурированной разметки Gmail и проверки в почтовых клиентах.

Скилл изучает существующие шаблоны, данные и провайдера отправки. Для кодов подтверждения он учитывает читаемость письма, срок действия, начальные нули, связь с попыткой входа и реальные ограничения AutoFill. Для заказов и бронирований помогает выбрать поддерживаемую разметку и проверить условия допуска Gmail. Он не обещает принудительно включить Copy code или получить доступ к чужой почте.

Установка в Codex:

Codex
$skill-installer install https://github.com/wladislaw353/agent-skills/tree/main/skills/email-development

Для явного вызова используйте $email-development. В инструкции для Claude Code описана установка коллекции и её обновление. После установки плагина используйте /agent-skills:email-development, при ручной установке папки в ~/.claude/skills/ — /email-development.

Пример задачи: «Проанализируй наши письма с кодами подтверждения. Улучши HTML и текстовую версию, проверь доступность, совместимость и возможности Gmail. Подготовь результат для проверки». Скилл помогает с анализом и реализацией, отправка писем и изменение настроек домена требуют отдельного поручения.

Расширенный скилл также включает чек-лист совместимости тегов и CSS, проверку MIME-вложений, различия между логотипом в письме, Promotions и BIMI, безопасную генерацию JSON-LD и жизненный цикл приглашений event.ics. Проверки отделяют подтверждённый результат от возможностей, которые ещё нужно испытать в реальном почтовом клиенте.