@expertum/cap-email-plugin

@expertum/cap-email-plugin

A SAP CAP plugin that provides annotation-driven email automation for CAP entities. Emails are triggered on entity lifecycle events (INSERT, UPDATE) and dispatched via configurable email clients.

Features

• Annotation-based configuration — no custom handler code required
• Automatic trigger handling — emails sent on entity INSERT/UPDATE
• Template support — HTML templates with {{placeholder}} substitution
• BTP integration — leverages Destination Service for OAuth2 authentication
• Extensible architecture — swappable email clients via cds.requires.kinds
• Email logging — plugin-owned log entity tracks send status and errors

Prerequisites

• SAP CAP (@sap/cds >= 9)
• Node.js >= 22 (required for ESM + @cap-js/cds-test compatibility)
• BTP Destination Service (for Microsoft Graph provider)

Installation

npm install @expertum/cap-email-plugin

Quick Start

1. Annotate your entity

@email.enabled: true
entity Orders {
  key ID     : UUID;
  orderNumber : String;
  status      : String;
  contactEmail: String;
}

That's it for a minimal setup. The plugin defaults to:

• Template: Orders.html (convention-based on entity name)
• Trigger: INSERT
• Recipient: req.user.email (from XSUAA context)

2. Create a template

Place an HTML template in your project:

email-templates/Orders.html

<h1>Order Confirmation</h1>
<p>Your order {{orderNumber}} has been received.</p>

Placeholders use {{fieldName}} syntax, where fieldName matches a field on the annotated entity. When an email is triggered, the plugin replaces each placeholder with the corresponding value from the entity record. Missing fields are replaced with an empty string.

3. Configure the email provider

In your application's package.json:

{
  "cds": {
    "requires": {
      "email": {
        "kind": "graph",
        "email": {
          "from": "noreply@example.com",
        },
      },
    },
  },
}

The graph kind uses Microsoft Graph API via a BTP destination. Configure the destination with OAuth2ClientCredentials in your BTP subaccount.

{
  "cds": {
    "requires": {
      "email": {
        "kind": "graph",
        "destination": "microsoft-graph",
        "email": {
          "from": "noreply@example.com",
        },
      },
      "microsoft-graph": {
        "kind": "rest",
        "credentials": {
          "destination": "your-ms-graph-btp-destination",
        },
      },
    },
  },
}

Annotation Reference

All @email properties have sensible defaults. Only specify what you need to override.

Full annotation example

@email: {
  enabled: true,
  template: 'order-confirmation',
  trigger: ['INSERT', 'UPDATE'],
  condition: 'status = ''APPROVED''',
  recipientField: 'contactEmail',
  subject: 'Order {{orderNumber}} confirmed',
  rollback: true
}
entity Orders { ... }

Static recipient example

@email: {
  enabled: true,
  recipient: 'support@company.com',
  subject: 'New support request'
}
entity SupportRequests { ... }

Email Providers

Providers are registered as CAP service kinds. The plugin ships with:

Select your provider in package.json under cds.requires.email.kind.

How It Works

1. Entity INSERT/UPDATE triggers an after handler
2. Plugin evaluates @email annotations and optional conditions
3. Template is loaded from your project and rendered with entity data
4. Recipient resolved from @email.recipient, @email.recipientField, or req.user.email
5. Email dispatched asynchronously via the configured provider
6. Status logged; failures recorded in the plugin-owned log entity

Emails are sent after successful operations only. Failed transactions never trigger emails. By default, email failures do not roll back the originating transaction, but this is configurable via @email.rollback.

Plugin Architecture

cds-plugin.ts          → Entry point; registers handlers
lib/plugin.ts          → Core logic; attaches after handlers for @email entities
lib/basic.ts           → Base EmailService class (extends cds.Service)
lib/graph-mail.ts      → Microsoft Graph implementation
lib/template-engine.ts → Template loading and {{placeholder}} rendering

Development

npm install
npm test

Test App

A minimal CAP application lives at test/test-app/ for testing the plugin end-to-end. It depends on the plugin via "file:../../." so changes are picked up immediately without publishing.

test/test-app/
  package.json               ← plugin dependency + basic kind config
  db/schema.cds              ← Orders (minimal), Tickets (full), Products (control)
  srv/services.cds           ← TestService exposing all entities
  email-templates/           ← templates for annotated entities

To run the test app standalone:

cd test/test-app
npm install
npx cds serve

Tech Stack

• TypeScript (ESM)
• Node.js >= 22
• oxlint + Prettier
• @cap-js/cds-test + @types/jest (jest-style assertions)
• Conventional Commits (feat:, fix:, chore:, etc.)

License

Copyright 2026 Expertum Group Apache-2.0