Skip to main content

Sending Email from CM Admin 📧

Overview​

The CM Admin email feature allows you to send emails directly from CM Admin. This documentation outlines how to use CM Admin emails, including configuration and examples.

Usage​

To use CM Admin email, use the CmAdmin.send_email method.

Attributes​

  • from (optional)

    • Specify from whom the email should be delivered. Takes a string value.
    • If not specified, uses the default from email from project settings.

  • to (required)

    • Specify to whom the email should be delivered. Takes an array or single email address.

  • cc (optional)

    • Specify carbon copy recipients. Takes an array or single email address.

  • bcc (optional)

    • Specify blind carbon copy recipients. Takes an array or single email address.

  • reply_to (optional)

    • Specify reply-to email address. Takes a string value.

  • subject (required)

    • Subject of the email. Takes a string value.

  • template (optional)

    • Template of the email. Takes a symbol value.
    • Options: :blank, :standard (default)

  • partial_file_path (optional)

    • Partial file path of the email template. Takes a string value.

  • partial_locals (optional)

    • Partial locals for the email template. Takes a hash value.

  • body (optional)

    • Body of the email. Takes an HTML string or plain text string.

  • button_text and button_link (optional)

    • If the email template requires a button with a link, use these attributes.

  • attachments (optional)

    • If the email requires attachments, use this attribute.

  • record (optional)

    • Associate the email log with a specific record. Takes an ActiveRecord object.
    • Automatically sets module_name, record_type, record_id, and record_url on the email log.

  • notify_on_failure (optional, default: true)

    • Whether to send an admin failure notification email if delivery fails. Takes a boolean value.
    • Set to false for system-internal emails (e.g. failure notifications themselves) to prevent recursive loops.

Examples​

Here are some examples of how to use the CmAdmin.send_email method to send emails:

Basic Email with Partial Template​

CmAdmin.send_email(
  to: ['anbu@commutatus.com'],
  subject: "[DMSv2] New Prospect Created!",
  partial_file_path: '/cm_admin/mailers/prospect_admin_notification',
  partial_locals: { user: User.last }
)

With CC and BCC Recipients​

CmAdmin.send_email(
  to: 'user@example.com',
  cc: 'manager@example.com',
  bcc: ['admin@example.com', 'audit@example.com'],
  reply_to: 'noreply@example.com',
  subject: "Project Update",
  body: '<p>Here is the latest project update.</p>'
)

With Custom From Email​

CmAdmin.send_email(
  from: 'info@commutatus.com',
  to: ['anbu@commutatus.com'],
  subject: "[DMSv2] New Prospect Created!",
  partial_file_path: '/cm_admin/mailers/prospect_admin_notification',
  partial_locals: { user: User.last }
)
CmAdmin.send_email(
  to: ['info@commutatus.com'],
  subject: "New User Created!",
  partial_file_path: '/cm_admin/mailers/user_admin_notification',
  partial_locals: { user: User.last },
  button_text: 'View user',
  button_link: 'http://domain.com/user/1'
)

Simple HTML Content​

CmAdmin.send_email(
  to: ['anbu@commutatus.com'],
  subject: "[DMSv2] New Prospect Created!",
  body: '<p>Simple HTML content to be added here.</p>'
)

Note: button_text and button_link are optional parameters.

Email with Blank Template​

CmAdmin.send_email(
  to: ['anbu@commutatus.com'],
  subject: "[DMSv2] New Prospect Created!",
  template: :blank,
  body: '<p>Simple HTML content to be added here.</p>'
)

Email with Attachments​

CmAdmin.send_email(
  to: ['anbu@commutatus.com'],
  subject: "[DMSv2] New Prospect Created!",
  body: '<p>Simple HTML content to be added here.</p>',
  attachments: [
    {
      filename: 'sample.pdf',
      file_content: '...'
    },
    {
      filename: 'sample.pdf',
      url_path: '...'
    }
  ]
)

Configuration​

Email Logging​

By default, email logging is disabled. To enable it, add the following to your initializer:

CmAdmin.config.enable_email_logging = true

When enabled, all emails sent via CmAdmin.send_email will be logged in the cm_email_logs table with delivery status, failure reasons, and recipient tracking.

To set up the required table, run the generator:

rails g cm_admin:add_email_logs
rails db:migrate

Important Notes​

Attachments​

  • Attachments should be an array of hashes
  • Each hash should have exactly two keys:
    1. filename - Name of the file
    2. file_content OR url_path - Either base64 encoded content or URL path

File Content Encoding​

The file_content should be a base64 encoded string of the file content/blob. You can use:

  1. From file path: Base64.encode64(File.open(file_path).read)
  2. From URL: Base64.encode64(URI.open(file_url).read)