How Does Double Opt-In (DOI) Work in Piano ESP?

How DOI Works in Piano ESP

By default, mailing lists in Piano ESP use Double Opt-In (DOI): new subscribers must confirm their subscription via a verification email before they can receive newsletters. This protects mailing list health, supports compliance with common email-marketing regulations, and preserves deliverability.

Subscriber Lifecycle with DOI Enabled

When a contact is added to a mailing list configured for DOI:

1. The contact is created or added in Pending Verification status.

2. Piano ESP sends a DOI verification email.

3. The contact becomes Active only after clicking the confirmation link/button in that email.

4. Until confirmation, the subscriber will not receive newsletter or campaign emails.

Piano ID DOI vs. ESP DOI

Piano has separate verification flows for different products. It is important to understand the distinction:

These are independent processes. Confirming in one system does not automatically imply confirmation in the other, unless your integration explicitly uses Piano ID; confirmed status to influence ESP subscription behavior.

Configuring the DOI Email Campaign

Piano ESP DOI emails are sent by a Service campaign. To set up or edit the DOI campaign:

1. Navigate to Email → Campaigns → Service.

2. Create or edit your DOI campaign (Service type).

3. Ensure the campaign is linked to the correct mailing list(s). If no list is selected, the campaign may remain in Draft.

4. In the template, include the mandatory Email Confirmation Button:

   • It must be present and visible.

   • It cannot be removed.

   • If missing, hidden, or duplicated, the campaign may not activate.

5. Set the campaign status to Active.

6. Configure or customize the post-confirmation landing page in the campaign settings as needed.

Service vs. Triggered DOI Campaigns

Some implementations use:

• Service DOI campaigns as the default DOI email (common and often sufficient).

• Triggered DOI campaigns for more customized behavior in cases where the subscribing email is already known in ESP or Piano ID.

If a custom DOI campaign is not active or not properly linked, Piano ESP will fall back to the default Service DOI campaign.

DOI Behavior Across Apps and Repeat Subscriptions

Behavior can vary based on the verification mode configured for your organization:

• Single Verification Mode: A DOI confirmation email is sent only the first time a user subscribes to a mailing list. All subsequent subscriptions by the same user undergo no additional verification.

• Always Verify Mode: A DOI confirmation email is sent each time a user subscribes to a mailing list, regardless of their previous verification status.

For more details about Mailing list health visit this documentation.

Subscriber Status Codes

Use these statuses to troubleshoot deliverability and subscription issues:

Troubleshooting: Subscriber Not Receiving Newsletters

1. Check subscriber status in ESP. If the user is 2 (Pending Verification), they will not receive newsletters until they confirm.

2. Confirm the DOI campaign is active and valid.

   • The Service DOI campaign must be Active.

   • The template must include the Email Confirmation Button.

3. Check delivery issues for DOI emails. Corporate email systems frequently filter DOI emails into spam or quarantine. Ask users to check their spam/junk folder and allowlist your sender domain.

4. Do not confuse campaign activation with disabling DOI. Making a DOI campaign inactive does not disable DOI if the mailing list's verification rule is still set to DOI.

If the DOI email is not being generated or is inconsistent between lists, collect steps to reproduce and contact Piano Support.

Disabling or Bypassing DOI

Piano ESP is designed to enforce list health. Fully removing verification is generally not supported without an approved alternative process. However, depending on your needs, there are three common options.

Key rule: Some form of verification method must remain in place.

Option 1: Temporarily Disable DOI for a Bulk Import (Support-Assisted)

This is the most common approach when migrating a previously verified list.

What to provide to Piano Support:

• ESP Site ID(s) and Mailing List ID(s) (or ESP IDs)

• Desired start and end date/time (include time zone)

• Estimated volume of imported contacts

• Description of your existing consent/verification process (proof that addresses are opt-in and high quality)

Important notes:

• Disabling DOI at the site level may affect all lists under that site. Confirm the scope with Support.

• This is typically time-bound and should be re-enabled immediately after the import.

• Addresses already in Pending will not automatically become Active when DOI is turned off. They must be reprocessed (see this section).

Option 2: Use the Paid Verification Alternative (Mailgun Validation)

Instead of DOI, you can use Verification (Mailgun email validation), which checks deliverability risk including syntax, mailbox validity signals, and known risk patterns such as spam traps.

• This is a paid feature. Coordinate with your Account Manager for availability and pricing.

• Verification can help reduce bounce rates and protect sender reputation. Providers may enforce strict thresholds; a bounce rate above approximately 2% is often a warning sign.

Option 3: Bypass DOI via API

For API-driven subscriptions, Piano can enable an internal setting allowing supported subscription endpoints to accept a DOI bypass parameter.

Supported endpoints (example):

• https://{HOST}/tracker/lucid/sub/{pubid}

• https://{HOST}/tracker/securesub

Example request body:

{
  "email": "user@example.com",
  "sqids": [12345],
  "skipDoiValidation": true
}

Important notes:

• This requires internal approval and is intended only when you have a robust alternative verification/consent process.

• The bypass applies only to API calls that include skipDoiValidation: true.

• Uploading or importing through the UI may still trigger DOI depending on configuration.

Not Retroactive: Already-Pending Subscribers

Changes to DOI behavior are generally not retroactive:

• If a subscriber is already 2 (Pending Verification), switching DOI off or enabling bypass does not automatically activate them.

• If you need pending users activated without confirmation, discuss options with Piano Support (e.g., re-importing under the correct verification mode, or an exception process).

Reporting Tips

If you see mismatches between dashboard metrics and the mailing list view:

• Dashboards may show historical counts for a selected date range.

• Mailing list pages typically show current state.

• Narrow the report range (e.g., to a single day) to better align the numbers.

When to Contact Piano Support

Contact Piano Support if you need to:

• Temporarily disable DOI for specific Site ID(s) or Mailing List ID(s)

• Enable API bypass support (skipDoiValidation)

• Switch a mailing list to the paid Verification method

• Investigate missing or inconsistent DOI email sends

• Handle large migrations where consent was already collected outside Piano

Include IDs, timelines, expected volumes, and a description of your consent/verification process to speed up review and approval.

Last updated: June 26, 2026