Inbox, Forms & Alert Banners — Developer Guide & Admin UI
1. Installation & Peer Setup
Section titled “1. Installation & Peer Setup”pnpm add @vicacha-devs/strapi-plugin-inbox2. Server Configuration (config/plugins.ts)
Section titled “2. Server Configuration (config/plugins.ts)”Add the plugin configuration to your Strapi v5 config/plugins.ts file:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "inbox": { enabled: true, config: { enableRateLimiting: true, doubleOptInRequired: true, }, },});
3. Strapi v5 Admin UI Tour
Section titled “3. Strapi v5 Admin UI Tour”Once enabled, the plugin registers its workspace and settings inside the Strapi v5 Admin panel using Strapi Design System v2 components:

Key Localized Admin UI Labels
Section titled “Key Localized Admin UI Labels”| Translation Key | Rendered UI Label |
|---|---|
page.ui.inbox_visual_form_builder_service_desk_casework |
Inbox, Visual Form Builder & Service-Desk Casework |
page.ui.starter_form_templates_active_forms |
Starter Form Templates & Active Forms |
page.ui.slug |
Slug |
page.ui.title |
Title |
page.ui.category |
Category |
page.ui.fields |
Fields |
page.ui.checklist |
Checklist |
page.ui.submissions |
Submissions |
4. Content-Type Entities, Locations & Schemas (strapi.documents)
Section titled “4. Content-Type Entities, Locations & Schemas (strapi.documents)”Registers three Collection Types (plugin::inbox.submission, plugin::inbox.subscriber, and plugin::inbox.alert-banner). Submissions capture dynamic form payloads and service-desk tickets; Subscribers manage double opt-in topic lists; Alert Banners drive time-bounded site-wide urgent tickers.
Where to Find Content-Type Entities in Strapi v5
Section titled “Where to Find Content-Type Entities in Strapi v5”- Content Manager:
/admin/content-manager/collection-types/plugin::inbox.submission,plugin::inbox.subscriber, andplugin::inbox.alert-banner(visible: true) - Content-Type Builder:
/admin/plugins/content-type-builderunder Collection Types (Inbox Submission,Inbox Subscriber,Inbox Alert Banner) - Plugin Workspace & Settings:
/admin/plugins/inbox(Service Desk Inbox, Subscribers, Alert Banners) and/admin/settings/inbox - Database Tables:
inbox_submissions,inbox_subscribers, andinbox_alert_banners
plugin::inbox.alert-banner — Inbox Alert Banner
Section titled “plugin::inbox.alert-banner — Inbox Alert Banner”Time-bounded multi-language urgent announcement ticker / banner
Kind:
collectionType· DB Table:inbox_alert_banners· Admin Location:/admin/content-manager/collection-types/plugin::inbox.alert-banner· Draft & Publish:No· i18n:No
| Attribute | Strapi Type | Required | Constraints / Target |
|---|---|---|---|
code |
string |
Yes | — |
title |
string |
Yes | — |
message |
text |
Yes | — |
severity |
enumeration |
Yes | enum: info, warning, urgent, celebration; default: "info" |
ctaLabel |
string |
No | — |
ctaUrl |
string |
No | — |
dismissible |
boolean |
No | default: true |
active |
boolean |
No | default: true |
priority |
integer |
No | default: 10 |
startsAt |
datetime |
No | — |
endsAt |
datetime |
No | — |
translations |
json |
No | default: {} |
plugin::inbox.submission — Inbox Submission
Section titled “plugin::inbox.submission — Inbox Submission”Form submission & Service-Desk Casework ticket
Kind:
collectionType· DB Table:inbox_submissions· Admin Location:/admin/content-manager/collection-types/plugin::inbox.submission· Draft & Publish:No· i18n:No
| Attribute | Strapi Type | Required | Constraints / Target |
|---|---|---|---|
referenceCode |
string |
Yes | — |
formSlug |
string |
Yes | — |
formTitle |
string |
No | — |
category |
enumeration |
No | enum: contact, service_desk, inquiry, application, volunteer, custom; default: "contact" |
status |
enumeration |
Yes | enum: new, read, under_review, scheduled, completed, rejected, archived; default: "new" |
priority |
enumeration |
Yes | enum: low, normal, high, urgent; default: "normal" |
department |
string |
No | default: "general" |
locale |
string |
No | default: "es" |
applicantName |
string |
No | — |
applicantEmail |
email |
No | — |
applicantPhone |
string |
No | — |
data |
json |
Yes | default: {} |
checklistItems |
json |
No | default: [] |
staffNotes |
text |
No | — |
assignedTo |
string |
No | — |
linkedBookingId |
string |
No | — |
linkedCertificateNumber |
string |
No | — |
formBuilderSubmissionId |
integer |
No | — |
ipAddress |
string |
No | private: true |
userAgent |
string |
No | private: true |
submittedAt |
datetime |
Yes | — |
secondaryDate |
json |
No | — |
plugin::inbox.subscriber — Inbox Subscriber
Section titled “plugin::inbox.subscriber — Inbox Subscriber”Double Opt-In newsletter and community topic subscriber
Kind:
collectionType· DB Table:inbox_subscribers· Admin Location:/admin/content-manager/collection-types/plugin::inbox.subscriber· Draft & Publish:No· i18n:No
| Attribute | Strapi Type | Required | Constraints / Target |
|---|---|---|---|
email |
email |
Yes | — |
fullName |
string |
No | — |
phone |
string |
No | — |
locale |
string |
No | default: "es" |
topics |
json |
No | default: ["announcements"] |
status |
enumeration |
Yes | enum: pending, confirmed, unsubscribed; default: "pending" |
confirmToken |
string |
No | private: true |
unsubscribeToken |
string |
Yes | private: true |
confirmedAt |
datetime |
No | — |
unsubscribedAt |
datetime |
No | — |
sourceFormSlug |
string |
No | — |
Strapi v5 Content Manager Integration (/admin/content-manager)
Section titled “Strapi v5 Content Manager Integration (/admin/content-manager)”Content Manager Sidebar Group:
Inbox & Omnichannel Broadcasts
Content Manager Entities & Components
Section titled “Content Manager Entities & Components”plugin::inbox.submission(Inbox Submission —/admin/content-manager/collection-types/plugin::inbox.submission)plugin::inbox.subscriber(Inbox Subscriber —/admin/content-manager/collection-types/plugin::inbox.subscriber)plugin::inbox.alert-banner(Inbox Alert Banner —/admin/content-manager/collection-types/plugin::inbox.alert-banner)

Why This Plugin Creates & Integrates Content Manager Entities
Section titled “Why This Plugin Creates & Integrates Content Manager Entities”@vicacha-devs/strapi-plugin-inbox registers all three of its entities (Inbox Submission, Inbox Subscriber, and Inbox Alert Banner) with pluginOptions['content-manager'].visible = true so service-desk coordinators, newsletter managers, and editors can combine the operational triage board in /admin/plugins/inbox with Strapi v5’s native Content Manager:
- Structured Casework & Cross-Entity Linking: In Content Manager,
Inbox Submission(plugin::inbox.submission) exposesreferenceCode,category,status,priority,department,checklistItems,linkedBookingId, andlinkedCertificateNumberwhile keepingipAddressanduserAgentprotected (private: true). - Subscriber Topic & GDPR Compliance Management: Filter
Inbox Subscriber(plugin::inbox.subscriber) bystatus(pending,confirmed,unsubscribed),locale, andtopicswhileconfirmTokenandunsubscribeTokenremain private. - Time-Bounded Urgent Alert Authoring: Author and schedule
Inbox Alert Banner(plugin::inbox.alert-banner) records (severity:info,warning,urgent,celebration,startsAt,endsAt,translations) directly in Content Manager.
How to Use in Strapi Content Manager (Step-by-Step)
Section titled “How to Use in Strapi Content Manager (Step-by-Step)”- Open in Content Manager: In the left sidebar, navigate to Content Manager -> Collection Types -> Inbox & Omnichannel Broadcasts and select Inbox Submission, Inbox Subscriber, or Inbox Alert Banner.
- Manage Urgent Alert Banners: Open Inbox Alert Banner (
/admin/content-manager/collection-types/plugin::inbox.alert-banner) to create or toggle site-wide announcements (RAMADAN-HILAL-1447,JUMUAH-LIVE-KHUTBAH,WINTER-BLANKET-CAMPAIGN). - Filter & Assign Service-Desk Submissions: Open Inbox Submission (
/admin/content-manager/collection-types/plugin::inbox.submission) to filter tickets bypriority = urgent,department, orstatus = under_review, and updateassignedToandstaffNotes. - Workspace vs. Content Manager: Use Content Manager for bulk filtering, alert banner scheduling, and subscriber list audits; use the Inbox Workspace (
/admin/plugins/inbox) for dynamic form schema design and interactive service-desk SLA triage.
Content Manager & Plugin Workspace Synchronization
Section titled “Content Manager & Plugin Workspace Synchronization”Content Manager Use Cases & Editorial Workflows
Section titled “Content Manager Use Cases & Editorial Workflows”Content Manager Use Case 1 — Scheduling Multilingual Urgent & Celebration Alert Banners
Section titled “Content Manager Use Case 1 — Scheduling Multilingual Urgent & Celebration Alert Banners”- Why & What it is for: Publish time-bounded header banners for Ramadan Hilal confirmation (
severity: 'celebration'), Friday live khutbah streams (info), or emergency relief appeals (urgent). - How to use in Content Manager: Open
/admin/content-manager/collection-types/plugin::inbox.alert-banner, click + Create new entry, setcode,title,message,severity,startsAt,endsAt, andtranslations, and save.
Content Manager Use Case 2 — Auditing Service-Desk Submissions & Linking Bookings/Certificates
Section titled “Content Manager Use Case 2 — Auditing Service-Desk Submissions & Linking Bookings/Certificates”- Why & What it is for: Filter high-priority counseling or matrimonial requests in Content Manager and link them to an appointment (
linkedBookingId) or certificate (linkedCertificateNumber). - How to use in Content Manager: Open
/admin/content-manager/collection-types/plugin::inbox.submission, filter bypriority = high, and update the record.
5. End-to-End Use Cases & Workflows
Section titled “5. End-to-End Use Cases & Workflows”Use Case 1 — Dynamic Public Form Builder & Service-Desk Casework Triage
Section titled “Use Case 1 — Dynamic Public Form Builder & Service-Desk Casework Triage”- What it is for: Render multi-step contact, matrimonial, counseling, or volunteer forms on the frontend and triage submissions with SLA priorities and staff checklists.
- How it works: Fetch form schemas via
GET /api/inbox/forms/{slug}, submit viaPOST /api/inbox/submit(creatingplugin::inbox.submissionwith areferenceCode), and track status viaGET /api/inbox/track/{referenceCode}.

Use Case 2 — Double Opt-In Newsletter & Topic Subscription Management
Section titled “Use Case 2 — Double Opt-In Newsletter & Topic Subscription Management”- What it is for: Collect GDPR-compliant newsletter and community topic subscribers with tokenized confirmation and 1-click unsubscribe.
- How it works:
POST /api/inbox/subscribecreates aplugin::inbox.subscriberinpendingstatus;POST /api/inbox/confirmandPOST /api/inbox/unsubscribeverifyconfirmToken/unsubscribeToken(private: true).

Use Case 3 — Time-Bounded Multilingual Site-Wide Alert Banners
Section titled “Use Case 3 — Time-Bounded Multilingual Site-Wide Alert Banners”- What it is for: Publish urgent announcements (e.g., Ramadan Hilal sighting, weather closure, live stream alert) in the website header ticker.
- How it works: Create
plugin::inbox.alert-bannerrecords withseverity(info,warning,urgent,celebration),startsAt,endsAt, andtranslations; fetch active banners viaGET /api/inbox/alerts.

6. REST API Endpoints (content-api & admin)
Section titled “6. REST API Endpoints (content-api & admin)”| Method | Endpoint Path | Scope | Controller Handler | Auth |
|---|---|---|---|---|
GET |
/api/inbox/forms |
content-api |
inboxController.listForms |
Public |
GET |
/api/inbox/forms/{slug} |
content-api |
inboxController.getFormBySlug |
Public |
POST |
/api/inbox/forms/{slug}/submit |
content-api |
inboxController.submitForm |
Public |
POST |
/api/inbox/subscribers |
content-api |
inboxController.subscribe |
Public |
GET |
/api/inbox/subscribers/confirm/{token} |
content-api |
inboxController.confirmSubscription |
Public |
GET |
/api/inbox/subscribers/unsubscribe/{token} |
content-api |
inboxController.unsubscribe |
Public |
GET |
/api/inbox/public/unsubscribe |
content-api |
inboxController.unsubscribe |
Public |
GET |
/api/inbox/alerts |
content-api |
inboxController.getActiveAlerts |
Public |
GET |
/inbox/settings |
admin |
inboxController.getSettings |
Bearer JWT |
PUT |
/inbox/settings |
admin |
inboxController.updateSettings |
Bearer JWT |
GET |
/inbox/templates |
admin |
inboxController.listTemplates |
Bearer JWT |
GET |
/inbox/form-builder-forms |
admin |
inboxController.listFormBuilderForms |
Bearer JWT |
POST |
/inbox/forms/sync-builder |
admin |
inboxController.syncFormBuilder |
Bearer JWT |
GET |
/inbox/forms |
admin |
inboxController.listForms |
Bearer JWT |
POST |
/inbox/forms |
admin |
inboxController.saveForm |
Bearer JWT |
POST |
/inbox/forms/from-template |
admin |
inboxController.createFromTemplate |
Bearer JWT |
GET |
/inbox/submissions |
admin |
inboxController.listSubmissions |
Bearer JWT |
PUT |
/inbox/submissions/{documentId}/casework |
admin |
inboxController.updateCasework |
Bearer JWT |
POST |
/inbox/submissions/{documentId}/schedule-booking |
admin |
inboxController.scheduleBooking |
Bearer JWT |
POST |
/inbox/submissions/{documentId}/issue-certificate |
admin |
inboxController.issueCertificate |
Bearer JWT |
GET |
/inbox/submissions/export-csv |
admin |
inboxController.exportCsv |
Bearer JWT |
POST |
/inbox/captcha/test |
admin |
inboxController.testCaptcha |
Bearer JWT |
GET |
/inbox/subscribers |
admin |
inboxController.listSubscribers |
Bearer JWT |
GET |
/inbox/alerts |
admin |
inboxController.getActiveAlerts |
Bearer JWT |
POST |
/inbox/alerts |
admin |
inboxController.upsertAlertBanner |
Bearer JWT |
7. Programmatic Server Usage (strapi.plugin & strapi.documents)
Section titled “7. Programmatic Server Usage (strapi.plugin & strapi.documents)”// Registered services on plugin "inbox": "settings", "formService", "submissionService", "subscriberService", "alertService"const pluginService = strapi.plugin("inbox")?.service("formService");
// Querying records via the Strapi v5 Document Service APIconst records = await strapi.documents("plugin::inbox.alert-banner").findMany({ limit: 25, sort: "createdAt:desc",});8. Troubleshooting & Verification
Section titled “8. Troubleshooting & Verification”- Admin panel changes not visible: Run
pnpm strapi buildafter modifyingconfig/plugins.ts. - Peer dependency isolation: Keep
hoistPattern: ["*", "!@strapi/*"]inpnpm-workspace.yamlso@strapi/*contexts are never duplicated. - TypeScript type-checking: Validate both
admin/tsconfig.jsonandserver/tsconfig.jsonviapnpm --filter <pkg> test:ts.