Files
chatwoot/app/mailers/conversation_reply_mailer.rb
T
Sony MathewandGitHub c420edce58 feat: branded email layouts for email inboxes (#14936)
## Description

Adds an API-only branded email layout feature for Email inbox replies.
Administrators can configure an account-level fallback layout and
per-email-inbox overrides with Liquid HTML using `{{ content_for_layout
}}`, and eligible outbound email replies/transcripts render through the
scoped layout when the account feature flag `branded_email_templates` is
enabled.

The feature is disabled by default and is manually controlled through
the normal account feature flag mechanism.

Fixes
https://linear.app/chatwoot/issue/CW-7514/branded-html-email-templates-per-inboxbrand

## Type of change

- [x] New feature (non-breaking change which adds functionality)
- [x] This change requires a documentation update

## How to test

1. Start Chatwoot locally and sign in as an administrator.
2. Enable the account feature flag for the account you are testing:

   ```ruby
   account = Account.find(<account_id>)
   account.enable_features!(:branded_email_templates)
   ```

3. Create or pick an Email inbox, then note the `account_id` and
`inbox_id`.
4. Configure an account-level fallback layout through the API using
authenticated admin headers:

   ```http
   PATCH /api/v1/accounts/:account_id/branded_email_layout
   Content-Type: application/json

   {
"branded_email_layout": "<html><body><header>Account Brand</header>{{
content_for_layout }}<footer>Account footer</footer></body></html>"
   }
   ```

5. Confirm `GET /api/v1/accounts/:account_id/branded_email_layout`
returns the saved account layout.
6. Configure an inbox-level override for the Email inbox:

   ```http
   PATCH /api/v1/accounts/:account_id/inboxes/:inbox_id
   Content-Type: application/json

   {
"branded_email_layout": "<html><body><header>Inbox Brand</header>{{
content_for_layout }}<footer>Inbox footer</footer></body></html>"
   }
   ```

7. Confirm `GET /api/v1/accounts/:account_id/inboxes/:inbox_id` returns
the inbox `branded_email_layout`.
8. Send an Email inbox reply and verify the outbound email body is
wrapped with the inbox layout around the generated reply content.
9. Clear the inbox layout by sending a blank value, then send another
reply and verify it falls back to the account layout:

   ```http
   PATCH /api/v1/accounts/:account_id/inboxes/:inbox_id
   Content-Type: application/json

   {
     "branded_email_layout": ""
   }
   ```

10. Clear the account layout with a blank value and verify Email replies
return to the existing no-layout behavior.
11. Verify validation behavior:
- Updating either API with a layout that omits `{{ content_for_layout
}}` returns `422`.
    - Updating either API with invalid Liquid returns `422`.
- Updating a non-Email inbox with `branded_email_layout` returns `422`.
- Disabling `branded_email_templates` and updating a layout returns
`422`.

## How Has This Been Tested?

Validation:

- `bundle exec rspec spec/models/email_template_spec.rb
spec/controllers/api/v1/accounts/branded_email_layouts_controller_spec.rb
spec/controllers/api/v1/accounts/inboxes_controller_spec.rb
spec/lib/email_templates/db_resolver_service_spec.rb
spec/mailers/conversation_reply_mailer_spec.rb`
- `bundle exec rspec
spec/enterprise/services/enterprise/billing/handle_stripe_event_service_spec.rb
spec/enterprise/services/internal/reconcile_plan_config_service_spec.rb`
- `bundle exec rubocop` on changed Ruby files, excluding generated
`db/schema.rb`
- `git diff --check` and `git diff --cached --check`
- YAML parsing for changed config/Swagger files
- `bundle exec rails routes -g branded_email_layout`

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] My changes generate no new warnings
- [ ] Any dependent changes have been merged and published in downstream
modules
2026-07-17 15:25:55 +05:30

226 lines
7.1 KiB
Ruby

class ConversationReplyMailer < ApplicationMailer
# We needs to expose large attachments to the view as links
# Small attachments are linked as mail attachments directly
attr_reader :large_attachments
include ConversationReplyMailerHelper
include ReferencesHeaderBuilder
include EmailAddressParseable
default from: ENV.fetch('MAILER_SENDER_EMAIL', 'Chatwoot <accounts@chatwoot.com>')
layout :choose_layout
def reply_with_summary(conversation, last_queued_id)
return unless smtp_config_set_or_development?
init_conversation_attributes(conversation)
return if conversation_already_viewed?
recap_messages = @conversation.messages.chat.where('id < ?', last_queued_id).last(10)
new_messages = @conversation.messages.chat.where('id >= ?', last_queued_id)
@messages = recap_messages + new_messages
@messages = @messages.select(&:email_reply_summarizable?)
prepare_mail(true)
end
def reply_without_summary(conversation, last_queued_id)
return unless smtp_config_set_or_development?
init_conversation_attributes(conversation)
return if conversation_already_viewed?
@messages = @conversation.messages.chat.where(message_type: [:outgoing, :template]).where('id >= ?', last_queued_id)
@messages = @messages.reject { |m| m.template? && !m.input_csat? }
return false if @messages.count.zero?
prepare_mail(false)
end
def email_reply(message)
init_conversation_attributes(message.conversation)
return unless smtp_config_set_or_development? || email_smtp_enabled? || (email_imap_enabled? && email_oauth_enabled?)
@message = message
prepare_mail(true)
end
def conversation_transcript(conversation, to_email)
return unless smtp_config_set_or_development?
init_conversation_attributes(conversation)
@messages = @conversation.messages.chat.select(&:conversation_transcriptable?)
Rails.logger.info("Email sent from #{from_email_with_name} \
to #{to_email} with subject #{@conversation.display_id} \
#{I18n.t('conversations.reply.transcript_subject')} ")
mail({
to: to_email,
from: from_email_with_name,
subject: "[##{@conversation.display_id}] #{I18n.t('conversations.reply.transcript_subject')}"
})
end
private
def init_conversation_attributes(conversation)
@conversation = conversation
@account = @conversation.account
@contact = @conversation.contact
@agent = @conversation.assignee
@inbox = @conversation.inbox
@channel = @inbox.channel
Current.account = @account
Current.inbox = @inbox
end
def should_use_conversation_email_address?
@inbox.inbox_type == 'Email' || inbound_email_enabled?
end
def conversation_already_viewed?
# whether contact already saw the message on widget
return unless @conversation.contact_last_seen_at
return unless last_outgoing_message&.created_at
@conversation.contact_last_seen_at > last_outgoing_message&.created_at
end
def last_outgoing_message
@conversation.messages.chat.where.not(message_type: :incoming)&.last
end
def sender_name(sender_email)
if @inbox.friendly?
I18n.t('conversations.reply.email.header.friendly_name', sender_name: custom_sender_name, business_name: business_name,
from_email: sender_email)
else
I18n.t('conversations.reply.email.header.professional_name', business_name: business_name, from_email: sender_email)
end
end
def current_message
@message || @conversation.messages.outgoing.last
end
def custom_sender_name
current_message&.sender&.available_name || @agent&.available_name || I18n.t('conversations.reply.email.header.notifications')
end
def business_name
@inbox.sanitized_business_name
end
def from_email
should_use_conversation_email_address? ? parse_email(@account.support_email) : parse_email(inbox_from_email_address)
end
def mail_subject
subject = @conversation.additional_attributes['mail_subject']
return "[##{@conversation.display_id}] #{I18n.t('conversations.reply.email_subject')}" if subject.nil?
chat_count = @conversation.messages.chat.count
if chat_count > 1
"Re: #{subject}"
else
subject
end
end
def reply_email
if should_use_conversation_email_address?
sender_name("reply+#{@conversation.uuid}@#{@account.inbound_email_domain}")
else
@inbox.email_address || @agent&.email
end
end
def from_email_with_name
sender_name(from_email)
end
def channel_email_with_name
sender_name(@channel.email)
end
def inbox_from_email_address
return @inbox.email_address if @inbox.email_address
@account.support_email
end
def custom_message_id
last_message = @message || @messages&.last
"<conversation/#{@conversation.uuid}/messages/#{last_message&.id}@#{channel_email_domain}>"
end
def in_reply_to_email
conversation_reply_email_id || "<account/#{@account.id}/conversation/#{@conversation.uuid}@#{channel_email_domain}>"
end
def conversation_reply_email_id
# Find the last incoming message's message_id to reply to
content_attributes = @conversation.messages.incoming.last&.content_attributes
if content_attributes && content_attributes['email'] && content_attributes['email']['message_id']
return "<#{content_attributes['email']['message_id']}>"
end
nil
end
def references_header
build_references_header(@conversation, in_reply_to_email)
end
def cc_bcc_emails
content_attributes = @conversation.messages.outgoing.last&.content_attributes
return [] unless content_attributes
return [] unless content_attributes[:cc_emails] || content_attributes[:bcc_emails]
[content_attributes[:cc_emails], content_attributes[:bcc_emails]]
end
def to_emails_from_content_attributes
content_attributes = @conversation.messages.outgoing.last&.content_attributes
return [] unless content_attributes
return [] unless content_attributes[:to_emails]
content_attributes[:to_emails]
end
def to_emails
# if there is no to_emails from content_attributes, send it to @contact&.email
to_emails_from_content_attributes.presence || [@contact&.email]
end
def inbound_email_enabled?
@inbound_email_enabled ||= @account.feature_enabled?('inbound_emails') && @account.inbound_email_domain
.present? && @account.support_email.present?
end
def choose_layout
return 'mailer/base' if branded_email_layout_action?
return false if action_name == 'reply_without_summary' || action_name == 'email_reply'
'mailer/base'
end
def branded_email_layout_action?
return false unless action_name.in?(%w[email_reply reply_without_summary])
return @inbox.branded_email_layout_available? if @inbox&.email?
@account&.feature_enabled?(:branded_email_templates) && EmailTemplate.account_branded_layout_template_for(@account).present?
end
def liquid_droppables
super.merge({
agent: current_message&.sender || @agent,
contact: @contact,
message: @message || @messages&.last
})
end
end