Automating Email Notifications in dotCMS Using Workflows

Push notifications are one of the most underrated and underused communication channels for many businesses. But when it comes to handling internal updates or customer messages, email notifications are still an essential part of daily operations. Many teams manage these tasks manually, which often causes delays and reduces efficiency.

Automating email notifications in dotCMS helps improve communication and workflow efficiency across your website. Instead of checking for new form submissions or content updates manually, you can create workflows to do it automatically. With dotCMS, you can set up a “Send an Email” workflow that alerts your team whenever new content is created or updated.

This guide explains how to configure SMTP settings, build an automated workflow, and connect it with your Contact Us form using a simple API call. You’ll learn how to set up the workflow, configure email settings, and connect it with your form using a simple API call.

What is a Workflow in dotCMS?

Imagine you’re running a small online magazine.

Whenever someone writes a new article, it goes through a few steps: the writer creates it, the editor checks it, and then it gets published on the website.

A workflow in dotCMS is just a way to make sure all those steps happen in the right order automatically. In dotCMS, a workflow defines the journey of your content from creation to publishing, updating, or even automated actions such as sending notifications or archiving.

Each workflow consists of a series of steps (like Draft, Review, Publish), and within those steps, you define actions users can take and sub-actions that happen automatically. These workflows are also the foundation of the dotCMS email automation workflow, which allows teams to send updates or alerts automatically.

To build advanced automations that align with your company’s goals, you can hire dotCMS developers experienced in creating scalable and efficient workflow systems.

Why Do We Need a Workflow?

In a real-world content system, not everything should be manual.For example, when someone submits a form, whether it’s a Contact Us form or a Feedback form, your team shouldn’t have to check for new entries every hour.

Instead, automating email notifications in dotCMS allows you to streamline what happens next:

• Instantly notify the right people whenever new content (such as a form submission) is created.
• Automatically save, publish, or send data without human intervention.
• Keep processes consistent, secure, and traceable.

When you begin with dotCMS, you unlock the full potential of dotCMS automation to ensure faster response times, improved collaboration, and better content management efficiency.

Use Case: Sending an Email After a Contact Form Submission

Let’s define our problem statement: We want to send an automatic email notification to the admin team whenever a new contact form is submitted through our website.

Without a workflow, someone would have to manually check submissions in the backend,  a slow, inefficient, and error-prone process.

With a Send an Email workflow, dotCMS automation can automatically trigger an email whenever new form content is created or updated.

SMTP configuration:

Before dotCMS can send any emails, it needs access to an SMTP server; that’s what we’ll configure next in the docker-compose.yml file.

    DOT_MAIL_TRANSPORT_PROTOCOL: smtp
    DOT_MAIL_SMTP_HOST: smtp-relay.brevo.com  --> Change according to your SMTP server 
    DOT_MAIL_SMTP_PORT: '587'
    DOT_MAIL_SMTP_AUTH: 'true'
    DOT_MAIL_SMTP_STARTTLS_ENABLE: 'true'
    DOT_MAIL_SMTP_USER: apikey
    DOT_MAIL_SMTP_FROM: {your_mailId}
    DOT_MAIL_SMTP_PASSWORD: xkeysib-{your_key}

How to Solve It with dotCMS

To automate this, we’ll create a custom workflow scheme for the Contact Form content type and add a Send an Email sub-action.Here’s how the process will look:

Form Submission → Workflow Trigger → “Send an Email” Sub-Action → Email Sent to Admin

We’ll break this into steps:

Step 1: Create a Workflow Scheme

1. Go to Schema→ Workflows
2. Click “Add Workflow Scheme”.
3. Name it something like “Contact Form Notification Workflow.”
4. Add a short description like “Triggers email notifications when a contact form is submitted.”

Step 2: Add a Workflow Step

1. Inside your new scheme, click “Add Workflow Step.”
2. Name it: “New Submission”
3. Set Order = 1
4. Keep Resolve Task = No (since this step just triggers an email, not resolution).
5. You can enable Schedule to auto-handle old submissions, but it’s optional here.

Step 3: Add an Action

1. Under the “New Submission” step, click “+ ADD” to add a new Action.
2. Name it: “Notify Admin”
3. Set:

Step 4: Add the Sub-Action Send an Email

1. In the Workflow Action panel, scroll to the Sub-Actions section.
2. Click the “+” icon to add a new Sub-Action.
3. Choose “Send an Email.”
4. Fill in the parameters:

This is the core of your dotCMS email automation workflow setup.

Step 5: Assign the Workflow to the Contact Form Content Type

1. Navigate to Schema→ Content Types → Contact Form.
2. Open the properties and assign your “Contact Form Notification Workflow.”
3. Save and test by submitting the form on your site.

Connecting Your Custom Form to the dotCMS API:

Now that you’ve created your custom Contact Us form, it’s time to connect it to dotCMS so that when someone fills out the form, their details are automatically sent and stored as content.

To make this connection, we’ll add a short script that sends your form data to dotCMS using the Workflow API.

Before You Start: Get These Three Things Ready

Before you integrate the API, you’ll need a few pieces of information from your dotCMS setup.

1. Get Your dotCMS API Token:

This token lets your form communicate securely with dotCMS.

• Go to System → Users → Click on your user → API ACCESS TOKENS.
• Click on the Request New Token button.
• Add the Label for your API token as “Contact Us Form API Token”.
• Set an Expiration Date and click OK.
• Copy the token you see; you’ll need it in your code.

2. Find Your Workflow ID

This ID tells the system which workflow action to trigger, in our case, the one that sends the email.

• Go to the Workflow you created earlier.
• Click on the step named “Notify Admin.”
• You’ll see an Action ID at the top-left corner of the page.
• Copy that Action ID to your workflow_id.

3. Find Your conhostId:

The conhostId links your form submission to the correct host in dotCMS.

• Go to Content → Show Query (you’ll find this option in the dropdown of the content search page).
• A dialog box will open and copy the conhost value from there.
• Keep it ready; you’ll use it in your form’s script.

Now, Let’s Integrate the API:

In the HTML container of your custom form, add the following script.This code handles sending your form data to dotCMS and receiving a response.

<script>
  const DOTCMS_API_TOKEN = {user_token};
  const apiUrl = "/api/v1/workflow/actions/{workflow_id}/fire";

  async function submitFormData(formData) {
      try {
          const response = await fetch(apiUrl, {
              method: "PUT",
              headers: {
                  Authorization: "Bearer " + DOTCMS_API_TOKEN,
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  contentlet: {
                      contentType: "ContactUsForm", // Replace with your content type 
                      username: formData.name,
                      email: formData.email,
                      subject: formData.subject,
                      message: formData.message,
                      conhost: {your_conhostId},
                  },
              }),
          });

          if (!response.ok) {
              const errorText = await response.text();
              throw new Error(`HTTP error! status: ${response.status} - ${errorText}`);
          }

          const result = await response.json();
          console.log("Data saved:", result);
          alert("Thank you for contacting us! Your message has been saved.");
      } catch (error) {
          console.error("Error submitting form data:", error);
          alert("Something went wrong. Please try again later.");
      }
  }

  // Trigger this function when the user clicks the Submit button
  const form = document.querySelector(".select-wrapper");
  form.addEventListener("submit", function (event) {
      event.preventDefault();
      const formData = {
          name: form.querySelector('input[type="text"]').value,
          email: form.querySelector('input[type="email"]').value,
          subject: form.querySelector('select').value,
          message: form.querySelector('textarea').value
      };

      submitFormData(formData);
      form.reset();
  });
</script>

This code sends your form data to dotCMS and triggers your Send an Email action, a perfect example of automating email notifications in dotCMS through a simple workflow.

Wrapping Up

You’ve now built a complete automated email workflow in dotCMS!

Whenever someone fills out your Contact Us form, dotCMS will:

1. Automatically capture their message as content.
2. Trigger your “Send an Email” sub-action.
3. Instantly send a notification email to your admin or team.

No manual steps, no delay, just smooth automation.

By automating email notifications in dotCMS, your business ensures faster communication, better efficiency, and seamless workflow execution without human intervention.

If you’re planning to scale your digital platform or need expert assistance in workflow automation, partnering with a CMS development company can help you design, implement, and optimize custom dotCMS solutions that fit your business needs perfectly.