Courier
A messaging framework that provides a flexible system for sending messages to identities through various channels like email.
courier
Install
composer require 'drupal/courier:^2.0'
Overview
Courier is a powerful messaging framework for Drupal that provides a flexible, plugin-based system for sending messages to identities (typically users) through various communication channels.
The module was originally designed for the RNG (Registration) module and introduces a sophisticated architecture with concepts like Channels (template entity types), Template Collections (groups of templates for different channels), Contexts (token definitions), and a Queue system for managing message delivery.
Courier bundles an Email channel out of the box and provides a plugin that links it to Drupal users. Other modules can extend Courier by creating new channels (SMS, push notifications, etc.) and identity channel plugins to support different recipient types.
The module uses a queue-based approach for message delivery, allowing for load balancing and improved performance on high-traffic sites. Messages are processed through Drupal's cron queue system, with an optional setting to skip the queue for debugging purposes.
Features
- Plugin-based architecture for extensible messaging channels (email, SMS, etc.)
- Template Collections that group message templates by channel type with token support
- Global Template Collections stored in configuration for exportable/importable templates
- Queue-based message delivery system with cron processing for scalability
- IdentityChannel plugins that bridge identities (users) to channels (email addresses)
- Token replacement system with context-aware token availability
- AJAX-powered template editing interface with Semantic UI components
- Channel preference management allowing prioritized fallback between channels
- Integration with Drupal's Token module for enhanced token browsing
Use Cases
Replace Drupal Core Emails
Use the Courier System submodule to replace Drupal's built-in user emails with rich, template-based messages. This allows site administrators to customize password reset emails, welcome messages, and account notifications using Courier's template system with full token support.
Event Registration Notifications
When combined with the RNG module, Courier handles all event registration communications. Event organizers can create customized confirmation emails, reminder messages, and updates that are sent to registrants through the queue system.
Multi-Channel Messaging
Extend Courier with additional channel modules (SMS, push notifications) to support multi-channel messaging. Set channel preferences so users receive messages through their preferred channel, with automatic fallback to alternatives if the primary channel fails.
Admin One-Off Messages
Use the Message Composer submodule to allow administrators to send quick one-off messages to individual users directly from the Drupal admin interface, useful for personalized communications or support responses.
Custom Module Integration
Developers can integrate Courier into custom modules by creating template collections, setting up contexts with appropriate tokens, and using the courier.manager service to send templated messages to any identity entity.
Tips
- Install the Token module for a better token browsing experience when editing message templates.
- Use Global Template Collections to make your message templates exportable with configuration management.
- Keep 'Skip queue' disabled on production sites to prevent performance issues with immediate email sending.
- Define custom IdentityChannel plugins to support sending messages to entity types other than users.
- Use the maintenance page to clean up stuck messages if your queue gets backed up.
Technical Details
Admin Pages 2
/admin/config/communication/courier
Configure global Courier settings including channel preferences for each identity type and queue behavior.
/admin/config/communication/courier/maintenance
Maintenance tools for managing the Courier message queue, including deletion of stuck messages.
Permissions 2
Hooks 1
hook_courier_identity_channel_info_alter
Alter the list of IdentityChannel plugins discovered by the plugin manager.
Troubleshooting 3
Check that cron is running regularly to process the message queue. Verify that the 'Skip queue' setting is disabled in production. Review the courier_message_queue_item table for stuck messages and use the Maintenance tab to clean them up if needed.
Ensure that the template collection has the correct context set with the required tokens. The context defines which tokens are available. Also verify that token values are being passed when calling sendMessage().
Verify that the user identity has an email address set. Check channel preferences in Courier settings to ensure courier_email is enabled for the user identity type. Review Drupal logs for any email delivery errors.
Security Notes 3
- The 'administer courier' permission is marked as restricted and should only be granted to trusted administrators.
- The 'courier bypass queue' permission can impact site performance and should be used sparingly.
- Message templates support token replacement - ensure tokens are properly escaped to prevent XSS vulnerabilities.