Support Requests

Audience: User, Org Admin, System Admin, Support Related: Audit And Logging · Security And Scoping

Authenticated Admin and Mobile users can submit a Support Request when platform support is configured. The request includes the user’s description and a bounded set of safe diagnostic context, with optional resized image attachment support and organization-level rate limiting.

Support requests must not collect passwords, provider secrets, API Tokens, private keys, or unrestricted page data. Recipient and confirmation behavior depends on the requesting user and the organization’s primary administrative contact.

Blackcap includes a lightweight Support Request flow in the Admin UI and Mobile UI for customer-facing SaaS/GCP deployments and self-hosted installs that want a simple way for signed-in users to ask for help without leaving the current screen.

This is intentionally not a case-management system. Blackcap generates a case number, sends email, audits the send result, and increments the next case number. It does not track status, assignment, comments, reopen/close state, SLAs, or third-party case-system synchronization.

Configuration

Support Requests use DB-backed platform settings under Configuration → Platform → Support:

Only System Admins can edit the platform Support group. Normal authenticated Admin and Mobile users can submit Support Requests when the platform Support settings are enabled and the support email address is valid.

User flow

When configured, the Admin user/account dropdown shows 🛟 Support Request directly above Logout, and the Mobile UI account dropdown shows the same action above Logout. The action opens a modal without leaving the page.

The modal captures:

• required issue description
• optional “what were you trying to do?” details
• current URL and page title
• visible screen errors/alerts on the current page
• visible current-screen form field labels and values when they appear safe to capture
• optional compressed image attachment, such as a screenshot or photo
• optional page context from window.BLACKCAP_SUPPORT_CONTEXT, data-support-context, or common record data attributes
• authenticated user and current organization context from the server
• browser user agent, client IP/location when available, and runtime metadata

The current-screen error capture is best effort. Pages can make important errors more explicit by rendering them with .flash.error, .alert-danger, .error-message, .field-error, [role="alert"], [aria-live="assertive"], or data-support-error.

Current-screen field capture is also best effort. The browser captures visible input, textarea, and select values outside the Support Request modal, including their nearby label/name/placeholder when available. Passwords, hidden fields, file fields, CSRF/session/token-like fields, and fields whose label/name/id look sensitive are skipped on the client and filtered again on the server. Pages can opt out a whole panel with data-support-exclude.

The optional image picker is intended for a screenshot or photo when text context is not enough. The browser resizes/compresses the selected image before sending it to Blackcap. The backend validates the MIME type, magic bytes, filename, and final size, then attaches the image to the support-team email and the requester confirmation email without storing the image in Blackcap.

Complete captured diagnostic context

The server builds the following bounded, sanitized context. A field may be blank when the browser, request path, organization record, GeoIP provider, or runtime cannot supply it.

The complete sanitized diagnostic context is size-limited. Individual strings, list lengths, nesting depth, and the overall context payload are trimmed when necessary.

Page-specific context extension

Any Admin or Mobile page can add safe context for support emails without changing the support service:

<script>
  window.BLACKCAP_SUPPORT_CONTEXT = {
    recipe_id: "recipe_abc123",
    recipe_title: "Weeknight Chili",
    source_url: "https://example.com/recipe"
  };
</script>

or:

<body data-support-context='{"display_id":"display_abc123","display_type":"hosted_receiver"}'>

The backend sanitizes client-provided context and treats it as diagnostic only. Never place secrets, raw tokens, cookies, reset links, SMTP passwords, OAuth credentials, or session identifiers in page context.

Sensitive data filtering

Before context is written into either email, Blackcap filters or trims suspicious keys such as:

• password/passwd
• secret/client_secret
• token/API token/access token/refresh token
• cookie/session/CSRF
• MFA/TOTP
• authorization/bearer/credential
• SMTP password

Large values are trimmed and overly large context is compacted. Raw image bytes are never included in the text diagnostic context; only image metadata such as filename, dimensions, and compressed size are listed there. The user confirmation email gets a customer-safe context view at the bottom under Information included with your request.

Rate limiting

Support Requests have a platform-configurable organization-level rate limit. The default is 10 requests per organization per rolling hour. System Admins can adjust this in Configuration → Platform → Support → Organization Requests Per Hour. Setting the value to 0 disables this Support-specific limit. The global security rate-limit toggle still controls whether Blackcap rate limiting is active at all.

When the limit is reached, the user gets a clear message such as:

Test Org has reached the platform support request limit of 10 requests per hour. Please wait and try again.

The rate-limit check happens before a case number is reserved, so blocked requests do not consume case numbers.

Case numbering

Case numbers are generated from the platform prefix and the platform next number:

BC00001

The numeric setting is reserved and incremented through the centralized settings service using an immediate database transaction. This prevents duplicate case numbers under concurrent requests.

A failed SMTP send can consume a reserved case number. That is intentional: Blackcap audits the failed attempt but does not tell the user the request succeeded. Skipped numbers are acceptable because the feature is email/audit only, not a full case table.

SMTP sender selection

Support Request email uses this order:

1. Active SMTP connection for the current organization.
2. Enabled platform SMTP settings.
3. Clear error if neither is usable.

For Support Requests, an active organization SMTP connection can send even when the platform email toggle used by normal recipe sharing/invite flows is disabled. Existing email behavior is preserved because the existing resolve_smtp_settings() behavior still gates normal sends with the platform email enabled flag.

The email From follows the selected SMTP configuration. The support-team email sets Reply-To to the requesting user and, when different, the organization's primary org admin/contact so the support inbox can reply to both people directly. If the header cannot be set safely, the requester and primary-admin emails are still included in the body.

When a non-primary-admin user submits a Support Request, the primary org admin/contact is kept in the customer-side loop by being copied on the requester confirmation email only. The primary org admin/contact is not CC'd on the support-team email because that message is for the configured support inbox. If the requester is already the primary org admin, no duplicate confirmation copy is added.

SMTP passwords and encrypted token references are never included in support emails or audit metadata. Audit/debug metadata only includes a source label such as organization_connection or platform.

Email templates

Support-team subject:

Support Request - Test Org - 6/17/26 - Case BC00001

Support-team body includes case number, organization, user, role, primary org admin/contact, whether the primary org admin/contact was copied on the customer confirmation, Blackcap app version, Git commit/build information, DB schema version, page URL/title, submitted description, visible screen errors, captured screen fields, optional image metadata, captured context, timestamp, and SMTP source.

User confirmation subject:

Blackcap Support Request Received - Case BC00001

The confirmation body thanks the user, includes the submitted message, organization, timestamp, primary org admin copy status when applicable, the optional image attachment, and the customer-safe diagnostic details at the bottom, including app version/build metadata.

Time zone and formatting

The subject date uses the Default organization time zone and the compact Blackcap date format:

m/d/yy

Email body timestamps use:

m/d/yy h:mm am/pm

Audit logging

Support Request actions audit:

• case number
• support recipient
• current URL
• send status
• whether the confirmation email was sent
• whether the primary org admin/contact was copied on the user confirmation
• SMTP source label
• UI source (admin or mobile)
• visible screen error count
• visible screen field count
• whether an image was attached

The full issue description is not logged. The email remains the source of the detailed message.

Troubleshooting

Testing checklist

• Platform Support settings have no default support email address.
• System Admin can enable/disable Support Requests and edit prefix/next case number/rate limit.
• Invalid support email is rejected.
• Normal users cannot edit Platform Support configuration.
• Authenticated users can open the modal when configured.
• Modal opens from multiple Admin screens without navigating away.
• Mobile account menu shows Support Request above Logout when configured.
• Mobile modal captures URL, title, visible errors, and page-specific context.
• Description validation works.
• Visible .flash.error or [role="alert"] text is included in support emails.
• Visible safe form field labels/values are included and sensitive field names are filtered.
• Optional image is compressed client-side, validated server-side, and attached without being stored.
• Organization hourly rate limit blocks the 11th request when the limit is 10 and does not consume a case number.
• Blackcap version, Git commit/build, and DB schema version are included in diagnostic context.
• Page context via window.BLACKCAP_SUPPORT_CONTEXT is included and sanitized.
• Organization SMTP is preferred when active.
• Platform SMTP fallback works when no org SMTP is active.
• No usable SMTP returns a clear error.
• Support-team email subject uses Support Request - Org Name - m/d/yy - Case BC00001.
• Support-team email Reply-To includes requester and primary org admin/contact when different.
• Support-team email does not CC the primary org admin/contact.
• Primary org admin/contact is copied on the requester confirmation email only when requester is different.
• User confirmation says a confirmation email was sent and includes safe diagnostics at the bottom.
• Confirmation-copy failure returns a warning rather than a false success message.
• Audit rows are created for success, partial success, and failure.
• Existing invite, password reset, recipe share, and other email flows still work.