Email Notifications

Introduction

CargoXplorer TMS includes a system email notification framework that sends transactional emails to users during key account lifecycle events. These notifications are fully customizable through the workflow EmailTemplate system, allowing organizations to brand and personalize their communications.

Notification Types

The system supports three types of automated email notifications:

Notification Type	Trigger	Purpose
Welcome Email	New user registration	Welcomes the user to the TMS platform
Organization User Added	User added to an organization	Notifies the user they've been added to an organization
Reset Password	Password reset request	Provides password reset instructions

Configuration

Enabling/Disabling Notifications

Email notifications can be enabled or disabled via application settings. Add the following to your appsettings.json or environment-specific configuration:

{
  "ClientUrls": {
    "ClientBaseUrl": "https://your-app.example.com",
    "BrandName": "Your Company TMS",
    "SendWelcomeEmail": true,
    "SendOrganizationUserAddedEmail": true
  }
}

Setting	Type	Default	Description
`ClientBaseUrl`	`string`	`""`	Base URL for login links in emails
`BrandName`	`string`	`"CX TMS"`	Brand name used in default email templates
`SendWelcomeEmail`	`boolean`	`false`	Enable/disable welcome emails for new users
`SendOrganizationUserAddedEmail`	`boolean`	`false`	Enable/disable organization added emails

Production Configuration

For production environments, you may want to disable certain emails initially:

{
  "ClientUrls": {
    "SendWelcomeEmail": false,
    "SendOrganizationUserAddedEmail": false
  }
}

Customization via EmailTemplate Workflows

Each notification type can be customized using the workflow EmailTemplate system. The system will execute the configured workflow to generate the email content, falling back to built-in defaults if the workflow is not found or fails.

Workflow IDs

Notification Type	Workflow ID
Welcome Email	`b2cbcec6-0e19-4c77-844d-a14a1ad5dfbf`
Organization User Added	`62f8ac8c-7ebe-4318-840d-f284b18d0aa0`

Template Variables

The following variables are passed to EmailTemplate workflows and can be used in your templates:

Welcome Email Variables

Variable	Type	Description
`firstName`	`string`	User's first name
`lastName`	`string`	User's last name
`email`	`string`	User's email address
`userId`	`string`	ASP.NET Identity user ID
`contactId`	`number`	TMS Contact ID
`loginLink`	`string`	URL to the login page
`brandName`	`string`	Configured brand name

Organization User Added Variables

Variable	Type	Description
`firstName`	`string`	User's first name
`lastName`	`string`	User's last name
`email`	`string`	User's email address
`userId`	`string`	ASP.NET Identity user ID
`contactId`	`number`	TMS Contact ID
`organizationName`	`string`	Name of the organization
`loginLink`	`string`	URL to the login page
`brandName`	`string`	Configured brand name

Example: Custom Welcome Email Template

Create an EmailTemplate workflow with the Welcome Email workflow ID:

workflow:
  workflowId: "b2cbcec6-0e19-4c77-844d-a14a1ad5dfbf"
  name: "Emails / Welcome"
  isActive: true
  workflowType: "EmailTemplate"
  executionMode: "Sync"
  version: "1.0"
  tags:
    - "email"
    - "welcome"
    - "user"

inputs:
  - name: "firstName"
    type: "text"
  - name: "lastName"
    type: "text"
  - name: "email"
    type: "text"
  - name: "userId"
    type: "text"
  - name: "contactId"
    type: "number"
  - name: "loginLink"
    type: "text"
  - name: "brandName"
    type: "text"

outputs:
  - name: "subject"
    mapping: "subject"
  - name: "body"
    mapping: "body"

activities:
  - name: composeEmail
    steps:
      - task: "Utilities/SetVariable@1"
        name: "buildSubject"
        inputs:
          name: "subject"
          value: "Welcome to {{ brandName }}, {{ firstName }}!"

      - task: "Utilities/SetVariable@1"
        name: "buildBody"
        inputs:
          name: "body"
          value:
            html: |
              <!DOCTYPE html>
              <html>
              <head>
                <meta charset="utf-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
              </head>
              <body style="font-family: Arial, sans-serif; margin: 0; padding: 20px;">
                <div style="max-width: 600px; margin: 0 auto;">
                  <h1 style="color: #333;">Welcome to {{ brandName }}!</h1>
                  <p>Hello {{ firstName }},</p>
                  <p>Your account has been created successfully. You can now access the platform using your email address.</p>
                  <p style="margin: 30px 0;">
                    <a href="{{ loginLink }}"
                       style="background-color: #007bff; color: white; padding: 12px 24px;
                              text-decoration: none; border-radius: 4px; display: inline-block;">
                      Login to Your Account
                    </a>
                  </p>
                  <p>If you have any questions, please contact your administrator.</p>
                  <p>Best regards,<br/>The {{ brandName }} Team</p>
                </div>
              </body>
              </html>
            text: |
              Welcome to {{ brandName }}!

              Hello {{ firstName }},

              Your account has been created successfully. You can now access the platform using your email address.

              Login here: {{ loginLink }}

              If you have any questions, please contact your administrator.

              Best regards,
              The {{ brandName }} Team

Example: Custom Organization User Added Template

workflow:
  workflowId: "62f8ac8c-7ebe-4318-840d-f284b18d0aa0"
  name: "Emails / Organization User Added"
  isActive: true
  workflowType: "EmailTemplate"
  executionMode: "Sync"
  version: "1.0"
  tags:
    - "email"
    - "organization"
    - "user"

inputs:
  - name: "firstName"
    type: "text"
  - name: "lastName"
    type: "text"
  - name: "email"
    type: "text"
  - name: "userId"
    type: "text"
  - name: "contactId"
    type: "number"
  - name: "organizationName"
    type: "text"
  - name: "loginLink"
    type: "text"
  - name: "brandName"
    type: "text"

outputs:
  - name: "subject"
    mapping: "subject"
  - name: "body"
    mapping: "body"

activities:
  - name: composeEmail
    steps:
      - task: "Utilities/SetVariable@1"
        name: "buildSubject"
        inputs:
          name: "subject"
          value: "You've been added to {{ organizationName }}"

      - task: "Utilities/SetVariable@1"
        name: "buildBody"
        inputs:
          name: "body"
          value:
            html: |
              <!DOCTYPE html>
              <html>
              <head>
                <meta charset="utf-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
              </head>
              <body style="font-family: Arial, sans-serif; margin: 0; padding: 20px;">
                <div style="max-width: 600px; margin: 0 auto;">
                  <h1 style="color: #333;">Welcome to {{ organizationName }}</h1>
                  <p>Hello {{ firstName }},</p>
                  <p>You have been added to <strong>{{ organizationName }}</strong> on {{ brandName }}.</p>
                  <p>You can now access the organization's resources and collaborate with your team.</p>
                  <p style="margin: 30px 0;">
                    <a href="{{ loginLink }}"
                       style="background-color: #007bff; color: white; padding: 12px 24px;
                              text-decoration: none; border-radius: 4px; display: inline-block;">
                      Access Your Account
                    </a>
                  </p>
                  <p>Best regards,<br/>The {{ brandName }} Team</p>
                </div>
              </body>
              </html>
            text: |
              Welcome to {{ organizationName }}

              Hello {{ firstName }},

              You have been added to {{ organizationName }} on {{ brandName }}.

              You can now access the organization's resources and collaborate with your team.

              Login here: {{ loginLink }}

              Best regards,
              The {{ brandName }} Team

Fallback Behavior

If an EmailTemplate workflow is not found, fails to execute, or returns empty content, the system automatically falls back to built-in default templates. This ensures emails are always sent even if custom templates are not configured.

The fallback templates:

Use the configured BrandName from application settings
Include a login link using the configured ClientBaseUrl
Feature a modern, responsive HTML design
Provide both HTML and plain-text versions

Background Processing

Email notifications are sent via Hangfire background jobs, ensuring:

Non-blocking user registration flow
Automatic retry on transient failures
Reliable delivery even during high load

Best Practices

Always test custom templates before deploying to production
Include both HTML and text versions for maximum compatibility
Keep emails concise - focus on the essential information
Use the provided variables to personalize content
Test across email clients - Gmail, Outlook, Apple Mail, etc.
Consider localization - create organization-specific templates for different languages
Monitor email delivery - check Hangfire dashboard for failed jobs

Introduction​

Notification Types​

Configuration​

Enabling/Disabling Notifications​

Production Configuration​

Customization via EmailTemplate Workflows​

Workflow IDs​

Template Variables​

Welcome Email Variables​

Organization User Added Variables​

Example: Custom Welcome Email Template​

Example: Custom Organization User Added Template​

Fallback Behavior​

Background Processing​

Best Practices​

Related Topics​