The Master Email Layout prerequisite
All Identity Management email is configured through the Email manager. Before any Identity Management email will send, you must set up a custom Master Email Layout. Without it, Identity Management emails, most notably password reset, silently do not send. This is true in both sandbox and production. Other email types (e.g. registration confirmation) may still appear to send even when the master layout is not configured, which makes the symptom confusing.
After configuring the master layout, also:
-
Verify your sending domain so emails appear to originate from your brand and pass SPF/DKIM/DMARC checks. The "From" address domain must be verified in Amazon SES, and if you change the domain later, re-verification is required.
-
Enable the specific Identity Management emails you want (welcome, password reset, etc.) in the Email manager and customize the templates.
The Identity Management email catalog and triggers
Identity Management can send the following emails. Each is optional except where noted, and each is toggled in Manage → Email manager.
Piano ID welcome email
Optional. Sent in these cases:
-
A user is created by the publisher via the Add new user button in the Piano dashboard (while Double Opt-In is disabled).
-
An API call to
conversion/registration/create. -
The user confirms their email when Double Opt-In is enabled.
NOT sent when a user registers by themselves on your website directly. To send a welcome message on self-registration, enable the User registration email instead (see below).
Piano ID user created by publisher
Optional. Sent when a user is created by the publisher via the Add new user button. Contains a link to set a password, and is functionally similar to the "Piano ID password reset request" email.
Piano ID password reset request
Optional. Sent when:
-
A user resets their own password.
-
A publisher clicks Reset password in a user's profile in the Piano dashboard.
-
A user created by the publisher attempts to log in for the first time.
The template MUST include the reset link variable:
<a href="{{full_reset_link}}">{{full_reset_link}}</a>
To enable it: go to Manage → Email manager, toggle on the Piano ID password reset request email, click the pencil icon to customize, and include the snippet above. If you have not already, also activate and customize the Master Email Layout so the reset email aligns with your brand. Verify your sending domain so emails appear to originate from you.
User registration
Optional. Sent when:
-
A user is created via the API endpoint
publisher/identity/registerorpublisher/user/register. -
A user registers on your website.
-
A user account is created during the checkout flow (a "User registration" email goes out).
NOT sent when the user is created during a bulk import.
Email confirmation
Mandatory when Double Opt-In is enabled, only sent in that case.
Sent when:
-
A user is created by the publisher via Add new user.
-
A user registers on your website.
NOT sent when a user registers via a social network when Double Opt-In is enabled.
Other contexts
-
"Completed Registration" email: fires when a user registers via a registration term from a registration offer template. Enable in the Email manager for the specific application.
-
"Free Access Granted" email: fires when the publisher (or an API call from an external system like HubSpot) grants free access to a user. Enable in the Email manager.
-
Passwordless login email: supports both magic-link and digital-code flows.
Quick decision matrix: which email fires when?
|
Trigger |
Welcome |
User-created-by-publisher |
User Registration |
Email Confirmation |
Password Reset |
|---|---|---|---|---|---|
|
User registers on website (DOI off) |
No |
No |
Yes (if enabled) |
No |
No |
|
User registers on website (DOI on) |
Yes, after confirm |
No |
No |
Yes (mandatory) |
No |
|
User registers via social (DOI on) |
No |
No |
Yes (if enabled) |
No |
No |
|
Publisher adds user via dashboard (DOI off) |
Yes (if enabled) |
Yes (if enabled) |
No |
No |
No |
|
Publisher adds user via dashboard (DOI on) |
No until user confirms; Yes after |
Yes (if enabled) |
No |
Yes (mandatory) |
No |
|
API |
Yes (if enabled) |
No |
No |
Per DOI rules |
No |
|
API |
No |
No |
Yes (if enabled) |
No |
No |
|
Bulk import |
No |
No |
No |
No |
No |
|
User created during checkout |
No |
No |
Yes (if enabled) |
Per DOI rules |
No |
|
User clicks "forgot password" |
No |
No |
No |
No |
Yes (if enabled) |
|
Publisher clicks "Reset password" in dashboard |
No |
No |
No |
No |
Yes (if enabled) |
|
Publisher-created user logs in for first time |
No |
No |
No |
No |
Yes (if enabled) |
Stopping duplicate or unwanted emails
When the publisher grants free access, several emails may fire if multiple templates are enabled. To send only, say, the password assignment email, review every toggle in the Email manager and disable everything you do not want.
When a welcome email is going out before the email address is confirmed in a Double Opt-In flow, the cause is usually the "User registration" toggle being on. Turn it off so the welcome only fires after confirmation.
Designing email templates: client compatibility
Email-client CSS/HTML support varies widely. When designing Piano Identity Management email templates:
-
No JavaScript. All email clients block JavaScript.
-
Limited CSS/HTML. Gmail supports
<style>inside<head>but NOT inside<body>. Outlook, Apple Mail, Android Mail each have different gaps. -
Test with Can I Use Email to confirm a feature is supported across the clients in your audience.
If users report blank or broken emails (often older clients without HTML support):
-
Configure your email system to send a plain-text version alongside the HTML version so old clients still get readable content.
-
Advise affected users to update their email client or device.
-
For high-priority users, send important content (e.g. registration URLs) via an alternative channel.
Dynamic values in email templates
The template editor exposes a list of available variables that interpolate per send. To include a unique value in an href (e.g. for tracking), use a variable from that list. There is no dedicated "unique email ID" variable, but the user ID is unique per user and works for that purpose.
Always confirm a variable exists by checking the editor's variable picker before publishing.
Passwordless login email customization
When you update the passwordless login email to include a styled button or link:
-
Apply the same CSS to both the text and button elements to keep styling consistent across clients.
-
If the button is generated but the magic-link URL is wrong or missing, check for double initialization of Piano Identity Management. Initializing both directly on the website and inside an integration script causes the link not to populate. Remove the duplicate so Piano Identity Management initializes once (typically inside the integration script).
-
Test in sandbox before promoting.
Expiration time displayed in the wrong unit
By default the passwordless template may pull the expiration value in minutes (e.g. 1440 minutes for 24 hours). To display "24 hours" instead:
-
Edit the email template and change the wording from "minutes" to "hours".
-
Remove the custom-field token that auto-injects the value in minutes, and manually type the value (e.g.
24 hours).
Email confirmation: digital_code vs. email_confirmation_url
In the Email Confirmation template, the digital_code variable is not always available. For example, when a user's email is changed via the publisher dashboard while still unconfirmed, the digital code is not generated.
-
Use
email_confirmation_urlto provide a click-through link as the primary confirmation path. -
Wrap the digital code with the
show_digital_codevariable so it appears only when a valid code exists.
The default Email Confirmation template uses this pattern; if a valid digital_code is present but not displayed, inspect the template for typos or markup errors that break the conditional.
SSO vs. non-SSO welcome emails
When provisioning users for an SSO-enabled application, send a different welcome email than for non-SSO users:
-
SSO users: include a direct, SSO-specific login link tied to the company so the user logs in via their identity provider without having to contact the admin.
-
Non-SSO users: send the standard welcome email without SSO-specific content to avoid confusion.
Use distinct templates (and the appropriate trigger) to keep these flows clean.
Localization of Identity Management email notifications
Translations of email copy follow the standard Piano localization flow. Strings wrapped for translation are managed in Manage → Localization, and dynamic content (e.g. subscription names) interpolates correctly into localized strings. Common pitfalls:
-
An "Email not valid" error returned during password reset should translate as the language-appropriate "email address not found" phrasing (e.g.
E-Mail-Adresse nicht gefundenin German). -
For dynamic phrases like "The auto-renewal for your subscription has been enabled", the translation must keep the subscription-name interpolation slot (e.g.
Die automatische Verlängerung für Abonnement wurde aktiviert). -
A global, language-wide change to a string that affects every customer on that locale typically must go through Piano product feedback rather than self-service editing.
Sandbox vs. production email behavior
In the Piano sandbox environment, transactional emails are recorded in logs for template verification but are NOT delivered to recipients. This is expected. You can use sandbox to confirm template rendering, variable substitution, and trigger firing, but you cannot use it to confirm end-to-end deliverability. For actual delivery testing, use production.
When configuring sandbox emails, also remember:
-
The Master Email Layout must be customized in sandbox too — without it, password reset emails will not send even in logs.
-
Different registration entry points (header button vs. barrier message) may have different email configurations. Verify each one independently. Discrepancies between sandbox and production are a common source of "emails work in one but not the other" tickets.
Troubleshooting production deliverability
If emails are not arriving in production:
-
Suppression/bounce lists. A previously hard-bounced address may be on the Amazon SES suppression list. Remove it before further sends will work.
-
Email template configuration. Confirm the relevant template is enabled in the Email manager AND the Master Email Layout is configured. Without the master layout, Identity Management emails will not send.
-
Sender domain verification. If the "From" domain was recently changed, re-verify in Amazon SES.
-
Recipient-side filtering. Emails may be in spam/junk or blocked by a corporate gateway. Have the user check.
-
Inspect the user's profile. The Emails tab on the user's profile in the dashboard shows the send status of each email.
-
Confirm trigger conditions. Cross-reference the matrix above; the trigger you expected may not be the one that should fire.
If none of these resolve the issue, escalate to Piano Support.
Mirror / "View online" link: NOT supported
The mirror or "View online" link feature is not currently supported in Identity Management transactional email templates, such as the password reset request email.
Related: third-party integration triggers
When integrating Piano with external systems (e.g. HubSpot), be aware that user-state changes you push via API can still trigger Piano emails:
-
Granting free access via API triggers the Free Access Granted email if it is enabled in Piano.
-
Creating a Piano user via the dashboard or API triggers the Piano ID user created by publisher email if enabled.
If you do not want these emails to fire from API-driven flows, disable them in the Email manager.