Email Confirmer
A comprehensive email address confirmation service for Drupal that provides an API, content entity, and utilities for verifying email addresses through confirmation links.
email_confirmer
Install
composer require 'drupal/email_confirmer:8.x-1.0'
Overview
Email Confirmer is a complete suite for email address confirmation in Drupal. It provides a centralized API and service that other modules can use to confirm email addresses, along with a content entity type to store and manage confirmation processes.
The module sends confirmation requests containing unique links to email addresses. Recipients can confirm or cancel the confirmation by clicking these links, which leads to a response form. Each confirmation stores detailed information including the email address, initiating user, IP address, creation timestamp, custom properties, realm (scope/module), status flags (pending, cancelled, confirmed, sent), and redirect URLs for different outcomes.
A key advantage of Email Confirmer is maintaining a database of confirmed email addresses, so users don't need to re-confirm the same address repeatedly for different purposes like newsletter subscriptions or profile updates. The module automatically purges old confirmation records via cron, with configurable lifetime settings.
The included Email Confirmer User submodule extends functionality to user-related events, such as requiring confirmation when users change their email addresses and synchronizing Drupal core's email verification status with the confirmation database.
Features
- Centralized email confirmation API and service that other modules can integrate with
- Custom content entity type (email_confirmer_confirmation) for storing and managing confirmation processes
- Configurable confirmation email templates with token support for personalization
- Response form allowing users to confirm or cancel email confirmations with customizable messages
- Optional direct confirmation mode that skips the response form for streamlined verification
- IP-based access restriction option to only accept responses from the originating IP address
- Private confirmation support limiting responses to the initiating user only
- Automatic purging of old confirmation records via cron with configurable lifetime (1 week to 1 year, or permanent)
- Queue-based delayed request dispatcher for rate-limiting confirmation email resends
- Realm system allowing modules to namespace their confirmations for filtering and organization
- Arbitrary property storage on confirmation entities for module-specific data
- Configurable redirect URLs after confirmation, cancellation, or error for different confirmation contexts
- User submodule: Email change confirmation requiring users to verify new email addresses before applying changes
- User submodule: Notification to current email address when email change is requested
- User submodule: Automatic confirmation recording on first user login and one-time login link usage
- Integration with Ultimate Cron module for scheduled purge jobs
Use Cases
Newsletter Subscription Confirmation
Use the email_confirmer service to verify newsletter subscription requests. When a user signs up for a newsletter, call $email_confirmer->confirm($email, ['subscription_type' => 'newsletter'], 'mymodule_newsletter') to initiate confirmation. Implement hook_email_confirmer() to process confirmed subscriptions and add users to the mailing list.
User Email Address Change Verification
Enable the Email Confirmer User submodule to require users to confirm new email addresses before the change takes effect. The original email remains active until confirmation, preventing unauthorized email hijacking and ensuring users maintain access to their accounts.
Contact Form Verification
Verify contact form submissions by requiring email confirmation before processing messages. Create a confirmation with custom properties storing the form data, then process the message in hook_email_confirmer() when confirmed.
Account Registration Double Opt-in
Implement double opt-in registration by using email confirmer alongside core user registration. The user submodule automatically records confirmations when users complete registration, building a verified email database.
API-based Email Verification for Headless Drupal
Use the email_confirmer service in custom REST endpoints to provide email verification for decoupled frontends. Create confirmations programmatically, customize response URLs to point to frontend routes, and query confirmation status via the API.
Tips
- Use the 'realm' parameter when calling the confirm() method to namespace confirmations for your module. This allows filtering confirmations by source and prevents conflicts between different use cases.
- Store custom data with confirmations using setProperty() on the confirmation entity. This data persists and is available in hook_email_confirmer() when processing responses.
- Set custom redirect URLs per confirmation using setResponseUrl() to direct users to context-appropriate pages after confirming, cancelling, or encountering errors.
- Mark confirmations as private using setPrivate() when they should only be respondable by the initiating user, preventing other authenticated users from hijacking the confirmation.
- The 'Consider existent confirmations' option in the user submodule reduces friction by not re-asking users to confirm previously verified email addresses.
- Token replacement in email templates supports [email-confirmer:confirmation-mail], [email-confirmer:confirmation-url], [site:name], [site:url], and other standard Drupal tokens.
Technical Details
Admin Pages 2
/admin/config/system/email-confirmer
Configure the core email confirmation service settings including confirmation expiration, email templates, response form behavior, and redirect URLs.
/admin/config/system/email-confirmer/user
Configure user-related email confirmation behaviors including email change confirmation and login-based confirmation recording.
Permissions 3
Hooks 1
hook_email_confirmer
Acts on email confirmation responses. Allows modules to react when a confirmation is confirmed or cancelled.
Troubleshooting 6
Ensure the 'access email confirmation' permission is granted to the appropriate user roles. This permission is disabled by default.
Increase the 'Response time limit' setting at /admin/config/system/email-confirmer. The default is 24 hours, but can be extended up to 48 hours.
Email confirmation entities must be deleted before uninstalling. Use the 'Delete all' contrib module (https://www.drupal.org/project/delete_all) to mass-delete all email_confirmer_confirmation entities.
Increase the 'Delay before re-send request' setting to enforce a longer wait between resend attempts. Requests made before the delay expires are queued for later delivery.
Verify the Email Confirmer User submodule is enabled and 'Require confirmation' is checked at /admin/config/system/email-confirmer/user. Also ensure users have the 'access email confirmation' permission.
Disable the 'Accept email confirmation responses only from the same IP address' setting if users need to confirm from different devices or networks.
Security Notes 6
- The 'administer email confirmations' permission is marked as 'restrict access' due to its sensitive nature. Only grant to trusted administrator roles.
- Enable IP restriction for confirmations in high-security scenarios, though be aware this may cause issues for users accessing from mobile networks or VPNs.
- The module uses HMAC-based hashes generated from email, timestamp, and IP using Drupal's private key for secure confirmation URLs.
- Private confirmations add an extra layer of security by ensuring only the account owner can respond to certain confirmations.
- The user submodule's notification to current email addresses helps detect unauthorized email change attempts.
- Consider the security implications of 'Skip response form' mode - while convenient, it may cause false confirmations if email security software previews links.