From 948781ce3cc23aa3bbe271b5cc9917d95538d2fe Mon Sep 17 00:00:00 2001 From: Martin Caetano Date: Sat, 31 Oct 2026 16:42:38 -0300 Subject: [PATCH] Document Audience delivery error management --- _audience/delivery-errors.md | 20 ++++ _config.yml | 1 + _i18n/en/audience/audience-overview.md | 6 + _i18n/en/audience/delivery-errors.md | 73 ++++++++++++ .../why-a-message-did-not-send.md | 1 + _i18n/es/audience/audience-overview.md | 6 + _i18n/es/audience/delivery-errors.md | 73 ++++++++++++ .../why-a-message-did-not-send.md | 1 + docs/editorial-work/delivery-errors.md | 104 ++++++++++++++++++ 9 files changed, 285 insertions(+) create mode 100644 _audience/delivery-errors.md create mode 100644 _i18n/en/audience/delivery-errors.md create mode 100644 _i18n/es/audience/delivery-errors.md create mode 100644 docs/editorial-work/delivery-errors.md diff --git a/_audience/delivery-errors.md b/_audience/delivery-errors.md new file mode 100644 index 00000000..e0ae0abf --- /dev/null +++ b/_audience/delivery-errors.md @@ -0,0 +1,20 @@ +--- +navigation_group: profile_data +languages: ["en", "es"] + +en: + title: Review delivery errors + description: Review failed email and phone destinations, export the affected details, and remove specific contact values from customer profiles. +es: + title: Revisa los errores de entrega + description: Revisa correos y teléfonos con errores, exporta los datos afectados y elimina valores específicos de los perfiles de clientes. + +permalink: review-delivery-errors +permalink_es: revisar-errores-entrega + +layout: guide +topic: audience +popular: false +--- + +{% translate_file audience/delivery-errors.md %} diff --git a/_config.yml b/_config.yml index 11902b34..398345a4 100644 --- a/_config.yml +++ b/_config.yml @@ -85,6 +85,7 @@ collections: - import-customer-profiles.md - custom-properties-and-events.md - personalization-tags.md + - delivery-errors.md - exporting-data.md - data-privacy-requests.md output: true diff --git a/_i18n/en/audience/audience-overview.md b/_i18n/en/audience/audience-overview.md index f33ff23f..ad62ea24 100644 --- a/_i18n/en/audience/audience-overview.md +++ b/_i18n/en/audience/audience-overview.md @@ -24,6 +24,12 @@ Profile data and permission to send are different. Before sending a campaign or Keep reading: [Who can I message? Consent and subscriber status]({% link _audience/consent-and-subscriber-status.md %}). +## Review delivery errors + +Open **Delivery errors** in Audience to review failed email addresses and phone numbers from campaigns and playbooks in one place. Inspect the reason and the profile before deciding whether to remove a contact detail. + +Keep reading: [Review delivery errors]({% link _audience/delivery-errors.md %}). + ## Import customer profiles Use imports when you need to bring existing customer data from a spreadsheet, CRM export, or another source into Hellotext. diff --git a/_i18n/en/audience/delivery-errors.md b/_i18n/en/audience/delivery-errors.md new file mode 100644 index 00000000..396e3e47 --- /dev/null +++ b/_i18n/en/audience/delivery-errors.md @@ -0,0 +1,73 @@ +Use **Audience → Delivery errors** to review email addresses and phone numbers associated with failed deliveries from campaigns and playbooks. You can inspect the customer's profile, export the affected details, and remove a specific value when you decide it should no longer be used. + +A delivery error does not always mean the customer's contact detail is wrong. Review the reason before changing the profile. + +## Open delivery errors + +1. Go to **Audience**. +2. Select **Delivery errors**. + +You can also open a campaign's **Partially delivered** status tooltip and select **Review errors**. The list opens with that campaign selected as its source. + +Each row represents one exact contact value on one profile. Repeated failures for the same value are grouped. The row count can therefore differ from the failed-message count in a report. A profile with both an affected email address and phone number can appear in two rows. + +If the message was never created or is still pending, see [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}). + +## Search and filter the results + +Search by name, email address, or phone number. In the more-options menu beside the search field, combine: + +- **Source:** campaigns, playbooks, or a specific source. +- **Error type:** invalid contact details, temporary errors, or errors that need review. +- **Channel:** email or SMS. + +Applied filters appear below the search field. Use a filter's close button to remove only that filter. Scroll to see more results. Changing the search or filters clears the selection. + +## Understand the reason + +| Error type | What to review | +| --- | --- | +| **Invalid contact details** | A destination reported as nonexistent or incorrect. Check the exact value for a typo or outdated information. | +| **Temporary errors** | A condition such as a full mailbox or an unavailable phone. The value may still be valid. | +| **Needs review** | A provider, sender, account, configuration, or unclear error. Investigate the reason before changing the customer's value. | + +A provider rejection or configuration problem is not proof that the recipient is invalid. Removing their email address or phone number does not fix the sending account. For channel investigation, see [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}). + +## Inspect the profile + +Select the customer's name or contact value to open the profile. Compare the affected value with the customer's other details and review **Activity** and **Notes**. + +The warning beside the value shows its error reason. Delivery failures in Activity include the destination and reason. List filters do not limit the other details you can inspect in the profile. + +## Export the error details + +1. Apply the search and filters you need. +2. To export every result, leave the selection empty. To export a subset, select its checkboxes. +3. Open the more-options menu. +4. Select **Export to file** or **Export selected**, as appropriate. + +Select all includes matching results that have not yet appeared while scrolling. Review the count before exporting. + +The CSV covers the contact details with errors that you are reviewing. To download customer properties, use the [profile export]({% link _audience/exporting-data.md %}). + +## Remove one or several values + +Removing a value removes that email address or phone number from the profile, not the whole profile. Other details and history remain. The removed value is no longer available for sending from that profile across channels: removing a phone number affects uses of that number beyond the failed SMS. + +To remove one value: + +1. Open the profile and find the exact value. +2. Select the removal control beside the failed value. The trash icon appears when you hover over or focus it. +3. Review the destination in **Remove email address** or **Remove phone number**. +4. Select **Remove**, or **Cancel** to keep it. + +To remove several values, select their rows and choose **Remove from profile (N)**. Review the email and phone counts, then confirm **Remove N** or cancel without changing them. + +Any category can be selected for removal; review whether it is appropriate, especially for temporary or configuration errors. Removal does not resend failed messages or change the customer's consent. If the value came from an import or integration, also check whether its source needs correcting. + +## Related guides + +- [Understand customer profiles]({% link _audience/customer-profiles.md %}) +- [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}) +- [Exporting data]({% link _audience/exporting-data.md %}) +- [Consent and subscriber status]({% link _audience/consent-and-subscriber-status.md %}) diff --git a/_i18n/en/troubleshooting-deliverability/why-a-message-did-not-send.md b/_i18n/en/troubleshooting-deliverability/why-a-message-did-not-send.md index 742f03d6..7c1bb15f 100644 --- a/_i18n/en/troubleshooting-deliverability/why-a-message-did-not-send.md +++ b/_i18n/en/troubleshooting-deliverability/why-a-message-did-not-send.md @@ -205,6 +205,7 @@ Do not include API tokens, passwords, or complete payment details. ## Related guides +- [Review delivery errors in Audience]({% link _audience/delivery-errors.md %}) - [Troubleshooting checklist]({% link _troubleshooting-deliverability/troubleshooting-checklist.md %}) - [Troubleshoot a playbook that did not trigger or send]({% link _journeys/troubleshoot-a-playbook-that-did-not-trigger-or-send.md %}) - [How Hellotext decides whether a playbook can send]({% link _journeys/how-hellotext-decides-whether-a-playbook-can-send.md %}) diff --git a/_i18n/es/audience/audience-overview.md b/_i18n/es/audience/audience-overview.md index 0c48307a..20e06648 100644 --- a/_i18n/es/audience/audience-overview.md +++ b/_i18n/es/audience/audience-overview.md @@ -24,6 +24,12 @@ Los datos del perfil y el permiso para enviar son cosas diferentes. Antes de env Sigue leyendo: [A quién puedo escribirle: consentimiento y estado de suscripción]({% link _audience/consent-and-subscriber-status.md %}). +## Revisar errores de entrega + +Abre **Errores de entrega** en Audiencia para revisar en un solo lugar los correos y teléfonos con fallos de campañas y misiones. Revisa el motivo y el perfil antes de decidir si eliminas un dato de contacto. + +Sigue leyendo: [Revisa los errores de entrega]({% link _audience/delivery-errors.md %}). + ## Importar perfiles de clientes Usa importaciones cuando necesitas llevar datos existentes de clientes desde una planilla, exportación de CRM u otra fuente a Hellotext. diff --git a/_i18n/es/audience/delivery-errors.md b/_i18n/es/audience/delivery-errors.md new file mode 100644 index 00000000..b1edc836 --- /dev/null +++ b/_i18n/es/audience/delivery-errors.md @@ -0,0 +1,73 @@ +Usa **Audiencia → Errores de entrega** para revisar los correos y teléfonos asociados a envíos fallidos de campañas y misiones. Puedes revisar el perfil, exportar los datos afectados y eliminar valores específicos. + +Un error de entrega no siempre significa que el dato sea incorrecto. Revisa el motivo antes de cambiar el perfil. + +## Abre los errores de entrega + +1. Ve a **Audiencia**. +2. Selecciona **Errores de entrega**. + +También puedes abrir la información del estado **Parcialmente entregado** de una campaña y seleccionar **Revisar errores**. La lista se abre filtrada por esa campaña. + +Cada fila representa un dato de contacto exacto de un perfil. Los fallos repetidos del mismo dato se agrupan. Por eso, el total de filas puede diferir del total de mensajes fallidos. Un perfil con correo y teléfono afectados puede aparecer en dos filas. + +Si el mensaje nunca se creó o todavía está pendiente, consulta [Por qué no se envió un mensaje]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}). + +## Busca y filtra los resultados + +Busca por nombre, correo o teléfono. En el menú de más opciones junto al buscador, combina: + +- **Origen:** campañas, **Playbooks** —misiones— o un origen específico. +- **Tipo de error:** datos inválidos, errores temporales o errores que requieren revisión. +- **Canal:** email o SMS. + +Los filtros aplicados aparecen debajo del buscador. Usa el botón de cierre de uno para quitar solamente ese filtro. Desplázate para ver más resultados. Cambiar la búsqueda o los filtros borra la selección. + +## Entiende el motivo + +| Tipo de error | Qué revisar | +| --- | --- | +| **Datos inválidos** | Un destino informado como inexistente o incorrecto. Revisa el valor exacto por si tiene un error de escritura o está desactualizado. | +| **Errores temporales** | Una condición como un buzón lleno o un teléfono no disponible. El dato puede seguir siendo válido. | +| **Requieren revisión** | Un problema del proveedor, remitente, cuenta o configuración, o una causa poco clara. Investiga el motivo antes de cambiar el dato del cliente. | + +Un rechazo del proveedor o un problema de configuración no demuestra que el destinatario sea inválido. Eliminar su correo o teléfono no corrige la cuenta de envío. Para investigar el canal, consulta [Por qué no se envió un mensaje]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}). + +## Revisa el perfil + +Selecciona el nombre o dato de contacto para abrir el perfil. Compara el valor afectado con los demás datos del cliente y revisa **Actividad** y **Notas**. + +El aviso junto al dato muestra el motivo del error. En Actividad, los fallos incluyen el destino y el motivo. Los filtros no limitan los demás datos del perfil. + +## Exporta los datos con errores + +1. Aplica la búsqueda y los filtros que necesites. +2. Para exportar todos los resultados, deja la selección vacía. Para exportar un subconjunto, marca sus casillas. +3. Abre el menú de más opciones. +4. Selecciona **Exportar a archivo** o **Exportar seleccionados**, según corresponda. + +Seleccionar todo incluye resultados del filtro que todavía no hayan aparecido al desplazarte. Revisa el contador antes de exportar. + +El CSV contiene los datos con errores que estás revisando. Para descargar las propiedades de los clientes, usa la [exportación de perfiles]({% link _audience/exporting-data.md %}). + +## Elimina uno o varios datos + +Eliminar un valor quita ese correo o teléfono del perfil, no el perfil completo. Se conservan los demás datos y el historial. Ese perfil deja de usar el valor para enviar en todos los canales: quitar un teléfono afecta los usos de ese número más allá del SMS que falló. + +Para eliminar un dato: + +1. Abre el perfil y encuentra el valor exacto. +2. Selecciona el control de eliminación junto al dato con error. La papelera aparece al pasar el cursor o darle foco. +3. Revisa el destino en **Eliminar correo** o **Eliminar teléfono**. +4. Selecciona **Eliminar** o **Cancelar** para conservarlo. + +Para eliminar varios, selecciona sus filas y pulsa **Eliminar del perfil (N)**. Revisa las cantidades de correos y teléfonos, y confirma **Eliminar N** o cancela sin cambiarlos. + +Cualquier categoría puede seleccionarse para eliminar datos; revisa si corresponde hacerlo, especialmente ante un error temporal o de configuración. La eliminación no reenvía mensajes fallidos ni cambia el consentimiento del cliente. Si el dato viene de una importación o integración, revisa también si necesitas corregirlo en su origen. + +## Guías relacionadas + +- [Cómo funcionan los perfiles de clientes]({% link _audience/customer-profiles.md %}) +- [Por qué no se envió un mensaje]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}) +- [Exportar datos]({% link _audience/exporting-data.md %}) +- [Consentimiento y estado de suscripción]({% link _audience/consent-and-subscriber-status.md %}) diff --git a/_i18n/es/troubleshooting-deliverability/why-a-message-did-not-send.md b/_i18n/es/troubleshooting-deliverability/why-a-message-did-not-send.md index 5f15e485..3f82f953 100644 --- a/_i18n/es/troubleshooting-deliverability/why-a-message-did-not-send.md +++ b/_i18n/es/troubleshooting-deliverability/why-a-message-did-not-send.md @@ -205,6 +205,7 @@ No incluyas tokens de API, contraseñas ni datos completos de pago. ## Guías relacionadas +- [Revisa los errores de entrega en Audiencia]({% link _audience/delivery-errors.md %}) - [Checklist de solución de problemas]({% link _troubleshooting-deliverability/troubleshooting-checklist.md %}) - [Soluciona una misión que no se disparó o no envió]({% link _journeys/troubleshoot-a-playbook-that-did-not-trigger-or-send.md %}) - [Cómo decide Hellotext si una misión puede enviar]({% link _journeys/how-hellotext-decides-whether-a-playbook-can-send.md %}) diff --git a/docs/editorial-work/delivery-errors.md b/docs/editorial-work/delivery-errors.md new file mode 100644 index 00000000..2f962b53 --- /dev/null +++ b/docs/editorial-work/delivery-errors.md @@ -0,0 +1,104 @@ +# Audience delivery errors — release documentation + +## Publication state + +Prepared on 2026-10-31 as a draft PR for the feature tracked in +[hellotext/hellotext#6772](https://github.com/hellotext/hellotext/issues/6772). +Do not merge or publish this guide until the production feature is implemented +and its released behavior has been checked against both translations. Merging +Help's main branch triggers publication. Auto-merge must remain disabled. + +The source is the agreed Audience prototype on +`codex/campaign-delivery-errors-preview`, revision +`e602ba1fe2c723c80a55e318d49b1140618bbabc`, and its +`docs/ui/campaign-delivery-errors.md` working record. The prototype uses +development-only example data; its local interactions do not establish +production persistence, provider classifications, or access permissions. + +## Article inventory + +This is a new guide; there is no earlier published article to preserve. + +| Locale | Source body | Planned route | State | +| --- | --- | --- | --- | +| English | `_i18n/en/audience/delivery-errors.md` | `/review-delivery-errors` | Draft; not published | +| Spanish | `_i18n/es/audience/delivery-errors.md` | `/es/revisar-errores-entrega` | Draft; not published | + +The shared stub is `_audience/delivery-errors.md`, in Audience's Profile data +& consent navigation group. Audience overview and the message-delivery +troubleshooting guide link to it in both languages. + +## Reader task and scope + +Find failed email addresses and phone numbers across campaigns and playbooks, +understand the reason, inspect the complete profile, export the relevant +contact values, and remove selected values only after reviewing them. + +The copy distinguishes contact-value counts from message counts and profiles. +It explains that temporary, provider, and configuration failures need review, +and that removing a phone affects every channel using that value. It does not +promise automatic retries, permanent suppression, restoration, an emailed +export, or a specific production provider-code mapping. + +## Section-by-section visual plan + +Screenshots are intentionally held for the implemented interface. The issue +contains prototype review captures, but those are not evidence of a released +feature. Do not publish those Spanish prototype captures as localized +production instructions. These are pending editorial checks before merge, +not completed visual work. + +| Section | Reader question / decision | Planned visual or reason for prose | +| --- | --- | --- | +| Open delivery errors | Where does the list live, and how does a campaign link to it? | Capture the Audience entry and a focused campaign status tooltip in each locale after implementation. | +| Find the details | Where are filters and how do I recognize an active filter? | Capture the more-options filter menu and one active removable filter; include the search field and count. | +| Understand the reason | Does this error mean the contact is invalid? | Keep the explanation in accessible text/table; another screen adds no diagnosis. | +| Inspect a profile | Which email or phone failed on this profile? | Capture the list beside a complete fictional profile with a warning beside the exact failed value. Use a tighter crop on narrow screens if needed. | +| Export | What is included in the CSV? | Steps and scope in prose; reuse menu context rather than duplicate the same menu. | +| Remove contact details | Am I removing a value or the profile? | Capture the concise single-value confirmation and, if materially different in production, the bulk confirmation with its counts. | + +No recipient-message example is planned: this guide manages failures and +contact data; it does not compose or send a message. A message preview would +not explain the management task. + +Follow the pinned `docs/editorial` skill and `docs/editorial-integration.md` +for final localized captures, original assets, capture records, Display P3 +PNG verification, static figure rendering, and desktop/mobile review. Existing +Help templates and visual assets are unchanged by this text draft. + +## Release verification before merge + +- Confirm Audience access, exact localized labels, source/error/channel filters, + campaign entry link, and full-profile behavior in the production implementation. +- Confirm grouping and count semantics, search, selection of all filtered + results including unloaded rows, and filtered versus selected CSV exports. +- Confirm actual error classifications and sender/configuration guidance. +- Confirm single and bulk removal persist only the intended contact values; + profile, other values, history, and subscription state remain as documented. + Verify phone removal across channels and reconcile queued-send behavior. +- Add and verify the final localized screenshots planned above. Match example + values to fictional accounts; do not send messages to prepare captures. +- Re-run the production build and security-header verifier, then review both + locales at desktop and mobile widths against the implemented feature. +- Merge only after #6772 is implemented and available to the guide's audience. + Record the deployment revision and check the public routes after publication. + +## Local verification + +Verified on 2026-10-31: + +- Production `yarn build` passed with Ruby 3.3.6 and Yarn 1.22.22, including + `script/verify_security_headers.rb`. Dependency files were left unchanged. +- Both localized HTML routes, Audience navigation entries, and search entries + were generated. All 76 internal links in the two guides resolve, including + section anchors. +- `docs/` and `AGENTS.md` remain excluded from the public build. The exported + editorial JavaScript modules match the committed source bytes in both locales. +- Browser DOM review at 1280×720 and 390×844 confirmed both article titles, + contents, localized links, section navigation, and error tables. At 390px, + both tables fit the 358px content area without page overflow. The existing + Help layout and styles were not changed; no screenshots were created or + accepted as final visual evidence in this draft. + +Production behavior and the localized screenshot plan above remain pending. +No deployment or public-page verification has occurred.