Lockout notification email template

When a caller hits the per-identity 24-hour failure cap (configurable per workspace; default 5 sessions in 24 hours), the platform sends a notification email to the contact’s email-on-file. This is the lockout notification and it has a fixed template.

This page documents the template so tenants who proxy the platform’s outbound mail (DMARC custodians, anti-spam vendors, downstream support systems) can recognise the message.

Trigger

The notification fires when identity_locked_per_24h event is written for a contact whose contact.email is non-null. The platform writes the event first, then enqueues the email; the email send is fire-and-forget on the conversation workflow’s critical path so a failed send does not block the rest of the conversation.

If the contact’s email is missing (it can be null on voice-channel contacts created from inbound calls without prior email-on-file), the notification is silently skipped.

Email body

Subject: Verification attempts on your account triggered a lockout

Body (en-US):

Hi $FIRST_NAME,

Someone (possibly you) tried to verify their identity on your account
several times in the last 24 hours but the answers didn't match.

For your account's safety, we've paused automated verification for the
next $LOCKOUT_DURATION_HOURS hours.

If this was you, please try again later or sign in via your usual
support channel and our team will help directly.

If this wasn't you, no action is required — your account is safe and
no information was shared. You may want to review your recent activity
in $BRAND_NAME when you next sign in.

-- The $BRAND_NAME team

Variables interpolated at send time:

• $FIRST_NAME — contacts.first_name, or “there” if unknown.
• $LOCKOUT_DURATION_HOURS — workspace’s lockoutDurationHours setting (default 24).
• $BRAND_NAME — brands.name for the workspace’s brand.

DKIM and sender

The email is sent from the workspace’s configured verification email channel (workspace_verification_configs.email_otp_channel_id). The channel’s domain governs DKIM signing and the sender display name.

Why it has this shape

Two design principles:

1. No-information rejection. The email never names the specific factor type that failed, the number of attempts, or the IP / device that originated them. Including those details would let an attacker confirm which information they probed was close.
2. Self-service unlock. The platform deliberately does NOT include a one-click unlock button. The lockout is the platform’s safety floor; resetting it requires either waiting out the lockout duration or escalating to the tenant’s human support team. The email tells the recipient how to do the latter.

Disabling

Workspaces cannot disable the lockout notification. It is a structural safety surface: a legitimate account holder who experiences a lockout deserves to know about it (and may take action: report to support, change credentials, escalate). A tenant who finds the notification volume excessive should consider raising the per-identity 24h cap rather than suppressing the email.

Overriding the copy

The default English template above can be overridden per-workspace via the agent_definitions.config.rejection_templates.lockout_email field on the system_verification agent definition. The override has access to the same interpolation variables.