Create email notification template

POST {VEZA_URL}/api/preview/notifications/email_templates

Body parameters:

Converting to Base64:

Request:

curl "https://{{VEZA_URL}}/api/preview/notifications/email_templates" \
-H 'authorization: Bearer '$token \
-d @reminder_with_attachment.json

{
  "value": {
    "name": "custom inactivity reminder",
    "subject_template": "Certification for {{WORKFLOW_NAME}} will be due soon",
    "body_template_base64": "U2lnbiBpbiBhdCB7e1dPUktGTE9XX1VSTH19IHRvIGZpbmlzaCByZXZpZXcgYnkge3tXT1JLRkxPV19DRVJUX0RVRV9EQVRFfX0uCg==",
    "attachments": [
      {
        "type": "IMAGE",
        "name": "logo",
        "contents_base64": " << base64-encoded string <64kb >> "
      }
    ],
    "usage": "ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY"
  }
}

Decoding the template: You can use base64 -D to decode the input. In this case, body_template_base64 decodes to:

Copy

Sign in at {{WORKFLOW_URL}} to finish review by {{WORKFLOW_CERT_DUE_DATE}}.

The response will contain the new email template, including the template id and configured attachments:

{
  "value": {
    "id": "b810e265-0c53-414c-88b6-4d71e6ca499e",
    "name": "custom inactivity reminder",
    "subject_template": "Certification for {{WORKFLOW_NAME}} will be due soon",
    "body_template": "Sign in at {{WORKFLOW_URL}} using your identity provider to finish review by {{WORKFLOW_CERT_DUE_ON_DATE}}.",
    "attachments": [
      {
        "type": "IMAGE",
        "name": "logo",
        "contents_base64": "string"
      }
    ],
    "usage": "ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY"
  }
}

Attachment

Veza recommends hosting your own high quality images and referencing them from your templates using HTML. However, you can upload attachments of 64kb or less in base64 format. Valid EmailTemplateAttachmentType types are:

• IMAGE (default)

Usage

Notifications inform reviewers of different types of events, such as when a due date is near, a result is re-assigned, or to provide periodic summaries of assigned reviews. You can customize the email sent for each event by setting the usage when uploading the template.

One template can currently exist per usage. To change the usage for a template, delete and re-create it.

Email batch size: When possible, notifications use a single email message, with all recipients in the "to" field. The maximum recipients is 20 by default. Veza sends additional emails when the limit is exceeded. The max recipients is adjustable by the Veza support team. ACCESS_WORKFLOW_REVIEWER_CHANGED emails are sent to individual recipients, unless triggered by a Smart Action or another action impacting several rows.

This table shows possible usage values and their matching setting in on the Email Notifications and Reminders page:

Delete email template

Delete an email template by id.

DELETE {VEZA_URL}/api/preview/notifications/email_templates/{id}

Request:

curl -X DELETE 'https://{{VEZA_URL}}/api/preview/notifications/email_templates/b810e265-0c53-414c-88b6-4d71e6ca499e' \
-H 'authorization: Bearer '$token

Response:

A successful response will be empty {}.

Get email notification template

GET {VEZA_URL}/api/preview/notifications/email_templates/{id}

Returns a single template, by id.

Request:

curl 'https://{{VEZA_URL}}/api/preview/notifications/email_templates/190f1358-fe4c-486f-8443-ac3d27790753' \
-H 'authorization: Bearer '$token

Response:

{
  "value": {
    "id": "190f1358-fe4c-486f-8443-ac3d27790753",
    "name": "new certification",
    "subject_template": "{{WORKFLOW_NAME}}",
    "body_template": "{{WORKFLOW_URL}}",
    "attachments": [],
    "usage": "ACCESS_WORKFLOW_STARTED"
  }
}

List email templates

GET {VEZA_URL}/api/preview/notifications/email_templates

Return all existing email templates, including IDs, usage, and attachment details.

Request:

curl 'https://{{VEZA_URL}}/api/preview/notifications/email_templates' \
-H 'authorization: Bearer '$token

Response:

All user-configured templates are returned within a values array:

{
  "values": [
    {
      "id": "aff71ba8-6674-49b8-8a02-ff9af1cc07bf",
      "name": "new certification",
      "subject_template": "New certification available for {{WORKFLOW_NAME}}",
      "body_template": "To view the new certification for {{WORKFLOW_NAME}}, log in at {{WORKFLOW_URL}} using your identity provider",
      "attachments": [],
      "usage": "ACCESS_WORKFLOW_STARTED"
    }
  ]
}

Update email template

PUT {VEZA_URL}/api/preview/notifications/email_templates/{id}

Update an existing template. The PUT method requires an update_mask indicating the fields to update.

Request:

curl -X PUT 'https://{{VEZA_URL}}/api/preview/notifications/email_templates/fb377947-a053-4026-bd4a-091be0761012' \
-H 'authorization: Bearer '$token \
-H 'Content-Type: application/json' \
-d '{
  "value": {
    "body_template": "<h1>An Access Workflow was Certified</h1><p>{{WORKFLOW_NAME}} was completed by {{WORKFLOW_CERT_COMPLETED_BY}} on {{WORKFLOW_CERT_COMPLETED_ON_DATE}}.</p><p>{{WORKFLOW_TEXT}} <a href=\"logo.png\"></p><p>To view the certification, visit {{WORKFLOW_URL}}</p>"
  },
  "update_mask": "value.body_template"
}'

Response:

{
   "value": {
      "id": "fb377947-a053-4026-bd4a-091be0761012",
      "name": "Updated Template",
      "subject_template": "example",
      "body_template": "<h1>An Access Workflow was Certified</h1><p>{{WORKFLOW_NAME}} was completed by {{WORKFLOW_CERT_COMPLETED_BY}} on {{WORKFLOW_CERT_COMPLETED_ON_DATE}}.</p><p>{{WORKFLOW_TEXT}} <a href=\"logo.png\"></p><p>To view the certification, visit {{WORKFLOW_URL}}</p>",
      "attachments": [],
      "usage": "ACCESS_WORKFLOW_STARTED"
   }
}

The update_mask parameter is required and specifies which fields should be updated. The mask uses dot notation to indicate nested fields (e.g., value.subject_template).

Test email template

POST {VEZA_URL}/api/preview/notifications/email_templates:test_template

Send an email to test recipients, using the specified template.

SendEmailFromTemplate will deliver a test email with the requested template to specified recipients. Emails can use:

• an existing template.id

• the current template for any usage

• the built-in default template for any usage

• a custom template specified in the request

Body parameters:

Test a new template

To send an email using a new template, the template object must contain values for body_base_64, name, usage, and subject_template.

template_base_64=$(cat ~/template.txt | base64)
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${VEZA_TOKEN}" \
     -d '{"template": {"body_template_base64": "'"${template_base_64}"'", "subject_template": "test email", "usage": "ACCESS_WORKFLOW_COMPLETED", "name": "test"}, "to": ["<recipient>"]}' \
     "${BASE_URL}/api/preview/notifications/email_templates:test_template"

Test an existing template

curl -X POST \
     -H "Authorization: Bearer ${VEZA_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"to": ["<recipient>"], "template": {"id": "fb377947-a053-4026-bd4a-091be0761012"} \
     "${BASE_URL}/api/preview/notifications/email_templates:test_template"

Test the default template for a usage

curl -X POST \
     -H "Authorization: Bearer ${VEZA_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"to": ["<recipient>"], "template": {"usage": "ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY"}, "default": true}}' \
     "${BASE_URL}/api/preview/notifications/email_templates:test_template"

Test the current template for a usage

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${VEZA_TOKEN}" \
     -d '{"template": {"usage": "ACCESS_WORKFLOW_COMPLETED"}, "to": ["<recipient>"]}' \
     "${BASE_URL}/api/preview/notifications/email_templates:test_template"

Overview

Administrators can customize email notifications sent to reviewers and other stakeholders during access reviews. These emails can include instructions, unique branding, and placeholders for metadata specific to the review (such as the review name, due date, or owner). Each notification type (usage) can have its own customized template.

Notification templates support HTML and CSS. They can include links to external images or you can upload small files to Veza. The Access Reviews > Settings > Notifications tab provides a straightforward interface for creating and editing templates.

This document includes steps to configure templates in Veza, and a full reference for event types, default templates, and supported placeholders.

Managing notification templates

Using the settings page

Veza provides a built-in user interface for managing email notification templates. This is the recommended method for creating, editing, testing, and deleting customizations to notifications.

To add a template:

1. Browse to Access Reviews > Settings > Notifications tab

2. Click Add Template to create a new notification template
3. Create the template by filling in the required fields:

   • Template name: A descriptive name for the template

   • Notification subject: Email subject line (supports placeholders)

   • Notification body: The content of the email (supports HTML and placeholders)

   • Notification event: The type of event the email template will apply to (also referred to as the "usage")

   • In the Images section, click Add images (optional)

     • Provide a Name for the image (used to reference the image in the template)

     • Upload an image by dropping a file in the designated area, or clicking Browse to select a file (maximum file size: 64KB).

     • You can add multiple images by clicking Add images again.

4. Save the template. It will appear on the list of templates on the Notifications tab, where you can edit, remove, or test it.

Using the API

Testing notification templates

You can test notification templates before implementing them in production:

1. Create and save your notification template through the UI

2. Navigate to the template list under Access Reviews > Settings > Notifications

3. Locate your template in the list and click the Test button in the Actions column

4. In the "Send Test Notification" dialog:

   • The template name will be pre-selected

   • Enter one or more recipient email addresses in the "Recipients" field (comma-separated)

   • Optionally add CC and BCC recipients

   • Click Send to deliver a test email

When testing templates, check that all placeholders are correctly replaced with sample values, verify HTML formatting displays as expected in email clients, and ensure that any links or buttons in the template are clickable and direct to the correct destinations. You should also confirm that any custom images are properly displayed.

To test a templates created via API:

1. Create the template using the appropriate API endpoint

2. Verify the template appears in the UI template list

3. Use the Test button in the UI to send a test email, or

4. Use the API test endpoint to send a test notification programmatically:

curl -X POST "{your_veza_url}/api/preview/notification-templates/{template_id}/test" \
-H "Authorization: Bearer {your_token}" \
-H "Content-Type: application/json" \
-d '{
  "recipients": ["test@example.com"],
  "cc": ["manager@example.com"],
  "bcc": ["admin@example.com"]
}'

Default Templates

See each section below for built-in HTML templates and placeholders:

<html>
 <head>
 <meta charset=\"UTF-8\" />
 </head>
</html>

<html>
    <head>
   <meta charset="UTF-8" />
   <title>Notification</title>
   <meta http-equiv="Content-Type" content="text/html charset=UTF-8" />
   <meta name="viewport" content="width=device-width,initial-scale=1" />
   <meta name="x-apple-disable-message-reformatting" />
   <style>
     * {
       font-family: Roboto, Arial, sans-serif;
     }
     body {
       padding: 0;
       margin: 0;
     }
     table {
       border: 0;
       width: 100%;
       border-spacing: 0;
     }
     table tr td {
       padding: 0;
     }
     .timestamp {
       color: #9097ad;
       font-size: 12px;
       line-height: 14px;
       padding-bottom: 5px;
     }
     .notification-text {
       font-size: 14px;
       line-height: 16px;
       color: #263040;
       padding-bottom: 30px;
     }
     .view-in-link a {
       text-decoration: none;
       background: #933aeb;
       border-radius: 10px;
       color: #ffffff;
       font-size: 14px;
       line-height: 16px;
       padding: 15px 35px;
       display: inline-block;
       font-weight: 500;
     }
     .ExternalClass {
       width: 100%;
     }
   </style>
 </head>
    <body style="padding: 0;">
     <table style="margin: 0; padding: 24px !important;">
       <tr style="margin: 0; padding: 0;">
         <th style="margin: 0; padding: 0 0 24px 0; text-align: left">
           <img src="cid:vezaLogo" style="width: 75px; display:inline-block;" alt="Veza logo" />
         </th>
       </tr>
       <tr>
         <td class="timestamp">{{WORKFLOW_TIME}}</td>
       </tr>
       <tr>
         <td class="notification-text">{{WORKFLOW_TEXT}}</td>
       </tr>
       <tr>
         <td class="view-in-link">
           <a href="{{WORKFLOW_URL}}" rel="noreferrer noopener" target="_blank"> View in Veza </a>
         </td>
       </tr>
     </table>
   </body>
</html>

<!DOCTYPE html>
<html lang="en">
   <head>
      <title> Access Reviews Digest </title>
   </head>
   <body style="
      padding: 50px 5px 0px 50px;
      font-family: Arial, sans-serif;
      text-align: center;
      background-color: #f1efef;">

      <img src="cid:` + email.VezaLogo + `" alt="Veza Logo" style="padding: 20px;">

      <!-- Table Container -->
      <div style="
         max-width: 750px;
         margin: auto;
         padding: 15px 0 15px;
         background-color: white;
         border-radius: 10px;
         ">

         <!-- Table Header -->
         <div>
            <div style="font-size: 28px; color: black; margin: 2px; font-weight:600;"> My Reviews </div>
            <span style="font-size: 22px; color: black; font-weight: 600;"> {{DIGEST_NOTIFICATION_PERIOD}} </span>
         </div>

         <!-- Table -->
         {{DIGEST_NOTIFICATION_TABLE}}

         <a href="{{ACCESS_REVIEW_URL}}">
            <button style="
               display: inline-block;
               background-color: #3c7bfa;
               color: white;
               border: none;
               border-radius: 7.5px;
               font-size: 18px;
               cursor: pointer;
               text-align: center;
               line-height: 1.5em;
               padding: 12px 14px;
               font-weight: 400;
               ">
               Go to My Reviews
            </button>
         </a>
      </div>


      <div style="
         font-size: 16px;
         color: #666;
         padding-top: 20px;
         padding: 10px 10px;">
         Copyright &copy; 2024 Veza.
      </div>

      <div style="
         font-size: 16px;
         color: #666;
         padding: 10px;
         padding-bottom: 50px;">
         To manage notifications, visit
         <a href="{{SETTINGS_URL}}" style="color: #3c7bfa;"> settings </a>
      </div>
   </body>
</html>

Usage

Each template you create is associated with a specific notification event (referred to as usage in the API). In the UI, this appears as the Notification event dropdown when creating or editing a template.

The available notification events are: Here's the aligned table of usages with their corresponding values from the list below:

Default workflow text

The built-in template for all messages uses a single {{WORKFLOW_TEXT}} placeholder in the subject and body. This default content depends on the notification event type, or "usage".

See the following list for the default workflow text for each notification event:

• ACCESS_WORKFLOW_STARTED

  • Subject Text

    Copy

    Access Workflow --> Certification: A new certification was started on workflow {{WORKFLOW_NAME}}

  • Body Text

    Copy

    A new certification was started for workflow {{WORKFLOW_NAME}}

• ACCESS_WORKFLOW_COMPLETED

  • Subject Text

    Copy

    Access Certification: A certification on workflow {{WORKFLOW_NAME}} has been completed

  • Body Text

    Copy

    A certification has been completed on workflow {{WORKFLOW_NAME}}

• ACCESS_WORKFLOW_REVIEWER_CHANGED

  • Subject Text

    Copy

    Access Certification: Assigned reviewers changed on certification for workflow {{WORKFLOW_NAME}}

  • Body Text (Previous Reviewer)

    Copy

    On a certification for workflow {{WORKFLOW_NAME}} the assigned reviewers has changed from {{WORKFLOW_CERT_OLD_REVIEWERS}} to {{WORKFLOW_CERT_REVIEWERS}}.

  • Body Text (New Reviewer)

    Copy

    {{WORKFLOW_TEXT}}: On a certification for workflow {{WORKFLOW_NAME}} the assigned reviewers has changed to {{WORKFLOW_CERT_REVIEWERS}}.

• ACCESS_WORKFLOW_OWNER_CHANGED

  • Subject Text

    Copy

    Access Workflow: A new owner assigned to workflow {{WORKFLOW_OWNER}}

  • Body Text

    Copy

    The owner of access workflow {{WORKFLOW_NAME}} has changed from {{WORKFLOW_OLD_OWNER}} to {{WORKFLOW_OWNER}}.

• ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY

  • Subject Text

    Copy

    Access Certification Reminder: Certification has had no activity from {{WORKFLOW_CERT_LAST_ACTIVITY_REVIEWER}} {{WORKFLOW_CERT_LAST_ACTIVITY_PHASE}} on workflow {{WORKFLOW_NAME}}

  • Body Text

    Copy

    User {{WORKFLOW_CERT_LAST_ACTIVITY_REVIEWER}} hasn't made progress on the certification started on {{WORKFLOW_CERT_STARTED_ON_DATE}} {{WORKFLOW_CERT_LAST_ACTIVITY_PHASE}}. User {{WORKFLOW_CERT_LAST_ACTIVITY_REVIEWER}} has {{WORKFLOW_CERT_LAST_ACTIVITY_ROWS_NEED_SIGN_OFF}} of {{WORKFLOW_CERT_LAST_ACTIVITY_ROWS_TOTAL}} rows that need to be signed off.

• ACCESS_WORKFLOW_REMINDER_DUE

  • Subject Text

    Copy

    Access Certification Reminder: Certification {{WORKFLOW_CERT_DUE_IN_PHRASE}} on workflow {{WORKFLOW_NAME}}

  • Body Text

    Copy

    The certification started on {{WORKFLOW_CERT_STARTED_ON_DATE}} for workflow {{WORKFLOW_NAME}} {{WORKFLOW_CERT_DUE_ON_PHRASE}}.

• ACCESS_WORKFLOW_ROW_ACCEPTED_AND_SIGNEDOFF

  • Subject Text

    Copy

    Access Review: Access for {{REVIEW_ACCEPTED_REJECTED_ROWS_PHRASE}} was approved in {{WORKFLOW_NAME}} Review

  • Body Text

    Copy

    In the access review {{WORKFLOW_NAME}}, access for {{REVIEW_ACCEPTED_REJECTED_ROWS_PHRASE}} was approved.
    
    Please find more details below:
    {{REVIEW_ACCEPTED_REJECTED_ROWS_DATA}}

• ACCESS_WORKFLOW_ROW_REJECTED_AND_SIGNEDOFF

  • Subject Text

    Copy

    Access Review: Access for {{REVIEW_ACCEPTED_REJECTED_ROWS_PHRASE}} was rejected in {{WORKFLOW_NAME}} Review

  • Body Text

    Copy

    In the access review {{WORKFLOW_NAME}}, access for {{REVIEW_ACCEPTED_REJECTED_ROWS_PHRASE}} was rejected.
    
    Please revoke the access described below:
    {{REVIEW_ACCEPTED_REJECTED_ROWS_DATA}}

• ACCESS_WORKFLOW_DIGEST_NOTIFICATION

  • Subject Text

    Copy

    My Reviews - {{DIGEST_NOTIFICATION_PERIOD}}

Image Attachments

From the Veza UI, you can add images directly through the "Add images" option. These will be automatically encoded and included in your template.

For API-based template management, small images under 64kb can be attached when configuring a template. The image must be base64-encoded and specified in the attachments field of the API request.

To use an attachment you have uploaded in a template, specify it by attachment.name, for example:

<img src="cid:<name_of_attachment>"

To embed high-resolution images in your templates, you should serve the content from a public URL, and use HTML to link and style it.

Placeholders

Use placeholders to include dynamic information in templates, such as decision timestamps, reviewer names, and other review or configuration metadata. Some placeholders are available depending on the template usage, and some are available for all templates, such as {{WORKFLOW_NAME}} and {{WORKFLOW_URL}}.

Placeholders for all templates

If a review (certification) exists for a configuration (workflow), the following placeholders are available:

Digest notification placeholders

Unique placeholders are available for the ACCESS_WORKFLOW_DIGEST_NOTIFICATION usage:

The {{DIGEST_NOTIFICATION_TABLE}} placeholder generates a tabular summary of assigned reviews, including the:

• Review name and link to the review

• Due date (if applicable)

• Total items needing review

• Status indicators (e.g., New, Overdue)

<!-- Table -->
<table style="
   border-collapse: collapse;
   width: 90%;
   margin: 20px auto;
   ">
   {{ range .Certifications }}
   <tr style="
      padding: 10px;
      ">
      <!-- Left Aligned -->
      <td style="text-align: left; padding: 10px;">
         <a href="{{ .CertUrl }}"
            style="
            text-decoration: none;
            color: #3c7bfa;
            font-size: 20px;
            font-weight: bold;">
            <span style="
               font-size: 20px;
               font-weight: bold;
               color: #3c7bfa;">
               {{ .CertName }}
            </span> <br>
            {{ if .DueDate }}
               <span style="
                  font-size: 15px;
                  font-weight: bold;
                  color: #666;
                  ">
                  Due {{ .DueDate }}
               </span>
            {{ end }}
         </a>
      </td>

      <!-- Right Aligned -->
      <td style="text-align: right; padding: 10px;">
         <a href="{{ .CertUrl }}"
            style="
            text-decoration: none;
            color: #3c7bfa;
            font-size: 20px;
            font-weight: bold;">
            <button style ="
               background-color: #d4d4d4;
               border: none;
               color: #666;
               padding: 6px 15px;
               text-align: center;
               margin: 2px 5px;
               cursor: pointer;
               font-size: 16px;
               border-radius: 31px;">
               {{ .WorkLeft }} need review
            </button>
            {{ if .Overdue }}
            <button style="
               background-color: #f7b5b5;
               border: none;
               color: #666;
               padding: 6px 15px;
               text-align: center;
               margin: 2px 5px;
               cursor: pointer;
               font-size: 16px;
               border-radius: 31px;
               ">
               Overdue
            </button>
            {{ else if .New }}
            <button style="
               background-color: aquamarine;
               border: none;
               color: #666;
               padding: 6px 15px;
               text-align: center;
               margin: 2px 5px;
               cursor: pointer;
               font-size: 16px;
               border-radius: 31px;">
               New
            </button>
            {{ end }}
         </a>
      </td>
   </tr>
   {{ end }}
</table>

ACCESS_WORKFLOW_OWNER_CHANGED placeholders

ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY placeholders

ACCESS_WORKFLOW_REMINDER placeholders

ACCESS_WORKFLOW_REVIEWER_CHANGED placeholders

Placeholders: Rejected and Accepted Rows

Usages ACCESS_WORKFLOW_ROW_ACCEPTED_AND_SIGNEDOFF and ACCESS_WORKFLOW_ROW_REJECTED_AND_SIGNEDOFF have unique placeholders:

Examples:

Number of impacted rows:

"2 rows" | "1 row" | "x rows"

List of approved or rejected rows:

<p>[Result Id 1] From srcType1 "SrcName1" (srcId1) to destType1 "destName1" (destId1)</p>
<p>[Result Id 2] From srcType2 "SrcName2" (srcId2) to destType2 "destName2" (destId2)</p>

List of approved or rejected rows, including notes:

<p>[Result Id 1] From srcType1 "SrcName1" (srcId1) to destType1 "destName1" (destId1) because of "reason 1"</p>
<p>[Result Id 2] From srcType2 "SrcName2" (srcId2) to destType2 "destName2" (destId2) because of "reason 1"</p>

When including notes, rows approved or rejected without a note will fall back to:

<p>[Result Id 1] From srcType1 "SrcName1" (srcId1) to destType1 "destName1" (destId1)</p>

List of approved or rejected rows without node IDs:

<p>[Result Id 1] From srcType1 "SrcName1" to destType1 "destName1"</p>
<p>[Result Id 2] From srcType2 "SrcName2" to destType2 "destName2"</p>

List of approved or rejected rows without node IDs, including notes:

<p>[Result Id 1] From srcType1 "SrcName1" to destType1 "destName1" because "reason 1"</p>
<p>[Result Id 2] From srcType2 "SrcName2" to destType2 "destName2" because "reason 1"</p>

Placeholders: Phrases

Some placeholders represent a collection of strings and variables and are used to construct the default messages: