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 — 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 Identity Management email templates:
-
No JavaScript. All email clients block JavaScript.
-
Limited CSS/HTML. Gmail supports