Розберемо два сценарії: вхід за одноразовим кодом і підтвердження бронювання. Для першого підготуємо лист і поле введення, для другого — 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.

Збираємо зрозумілий лист із даних бронювання

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 допомагає перевірити конкретну властивість. Перевіряйте отриманий лист на вузькому екрані, у темній темі та без зображень.

Додаємо логотип і PDF: одного HTML недостатньо

cid:brand-logo@example.com у HTML посилається на частину самого повідомлення. 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-вкладення. Це перевірка складання, ще не доставки. Сигнатури допомагають виявити переплутаний тип файлу, але не перевіряють його вміст чи належність квитка отримувачу. Якщо читання файлу не вдалося, складання зупиниться: повідомлення «квиток додано» не буде створено без квитка.

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 його не вмикає. Не публікуйте приватний PDF заради зручного URL. Використаний API описано в довіднику вкладень і stream transport.

Картка бронювання Gmail: дані та місце розмітки

Людина читає «майстер-клас, 21 листопада, 10:00». Розмітка передає ті самі факти машинно: підтверджене бронювання WS-1042 належить Alex, подія відбудеться за конкретною адресою. Gmail може використати їх у підтримуваному інтерфейсі бронювань. Ви не малюєте цей інтерфейс і не даєте команду автоматично додати подію до календаря.

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

Вставте блок між першим і другим блоками прикладу, до створення message. Він додає JSON-LD до head самого листа. JSON не має з’явитися у видимому тексті. Зміна SEO-розмітки сайту або прикріплення окремого 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 робить час у цю листопадову дату однозначним. Повну адресу вказано тому, що Google вимагає її для цього типу. Якщо в базі лише місто, спочатку отримайте справжню адресу майданчика; не вигадуйте обов’язкові значення. Склад полів задає контракт EventReservation.

Назва може містити лапки або буквальний </script>. JSON.stringify формує JSON, а заміна < на \u003c не дає значенню закрити HTML-блок. Після розбору JSON назва відновиться. &quot; не замінює лапки JSON — це зіпсує дані. Тут використовується формат JSON-LD для листів, а не виконуваний скрипт.

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

Promotions: як описати знижку, не сплутавши її з OTP

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

Рядок промолиста Gmail із позначкою 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%. Checkout має приймати CLAY15, а серверний строк акції — збігатися з availabilityEnds. PromotionCard потребує зображення та цільового URL. Використовуйте PNG/JPEG із пропорціями 4:5, 1:1 або 1.91:1. CID не замінює публічну адресу зображення. Валідна анотація не керує вибором вкладки й не гарантує показу. Дивіться механізм 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. Не використовуйте часовий пояс сервера. Перевіряйте, що кінець пізніший за початок, і явно обробляйте неіснуючий час при переході на літній режим. Для цілоденної події потрібен 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 у календарі має відповідати Content-Type: text/calendar; charset=utf-8; method=REQUEST у MIME. У 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 учасникаПеревірити відправника, учасника та версію, потім зберегти відповідь.

iMIP, RFC 6047 пов’язує календарні методи з поштою; iTIP, RFC 5546 визначає обмін. ATTENDEE у вхідному файлі не доводить особу відправника. Навіть зі сталим UID окремо перевірте повторний імпорт, оновлення та скасування в цільових календарях: успішний розбір файлу не доводить поведінку клієнта.

Як знайти місце, де лист зламався

СимптомПеревіркаВиправлення
Немає логотипаЗвірити cid у HTML з 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 пройдіть цикл запрошення → відповідь → перенесення → скасування. Записуйте клієнт, версію та результат замість загального «пошта працює».

Що вибрати для свого продукту

СценарійОсновний шляхМежа можливостей
Сайт, власний відправник SMSСемантика поля + прив’язка до домену. WebOTP там, де підтримуєтьсяНе читання всіх SMS і не доступ до листів
Android, можна змінювати SMSSMS Retriever APIGoogle Play services, формат повідомлення та хеш застосунку
Android, не можна додати хешSMS User Consent API, якщо сценарій відповідає умовамЗгода на одне повідомлення, обмеження відбору та часу очікування
Застосунок для iPhoneПоле oneTimeCode і системний AutoFillРозпізнаванням і показом підказки керує ОС
Код надходить електронною поштоюЗрозумілий лист + коректне поле + доступні системні підказкиWebOTP не є API читання електронної пошти
Помічник для чужих сайтів і застосунківДозволені платформні інтеграції з перевіркою призначенняОкремий продукт із доступом до чутливих даних

Таблиця описує напрями інтеграції, а не гарантії за брендом телефона. Наприклад, 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: створити спробу підтвердження; запустити очікування в застосунку; після успішного запуску запросити надсилання; надіслати код із хешем застосунку; отримати результат у receiver; передати код і спробу на сервер. Кожен етап може зламатися окремо. Неправильний release-хеш заважає застосунку отримати код, хоча 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 із менеджера паролів — ще одне окреме джерело, яке не слід змішувати з кодом, доставленим листом.

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

Покращити власне оформлення замовлення й побудувати помічника для будь-яких сайтів — різні за масштабом проєкти. У другому випадку спочатку потрібно визначити, де він працює: розширення браузера, вибраний постачальник автозаповнення 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. Перевірки відокремлюють підтверджений результат від можливостей, які ще потрібно випробувати в реальному поштовому клієнті.