Release Notes

Notification Templates API

Methods to list, create, update, and delete email templates.

The following requests change and preview the default templates for Access Workflow notification emails and Lifecycle Management Notifications.

Base URL and Authorization: As custom templates functionality is subject to change, these endpoints are currently available under the /preview namespace. To use the API, you will need to generate an API Key.

API Reference

The Notification Templates API provides programmatic access to manage email templates for Access Reviews and Lifecycle Management workflows. The API supports creating, updating, listing, and testing custom email templates.

List email templates

get
Authorizations
Responses
200
OK
application/json
get
GET /api/preview/notifications/email_templates HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Accept: */*

{
  "values": [
    {
      "id": "text",
      "name": "text",
      "subject_template": "text",
      "body_template": "text",
      "attachments": [
        {
          "type": 1,
          "name": "text",
          "contents_base64": "text"
        }
      ],
      "usage": 1,
      "body_template_base64": "text",
      "scope": 1,
      "entity_ids": [
        "text"
      ]
    }
  ]
}

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

Create email notification template

post
Authorizations
Body
Responses
200
OK
application/json
post
POST /api/preview/notifications/email_templates HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "value": {
    "name": "text",
    "subject_template": "text",
    "body_template": "text",
    "attachments": [
      {
        "type": 1,
        "name": "text",
        "contents_base64": "text"
      }
    ],
    "usage": 1,
    "body_template_base64": "text",
    "scope": 1,
    "entity_ids": [
      "text"
    ]
  }
}
{
  "value": {
    "id": "text",
    "name": "text",
    "subject_template": "text",
    "body_template": "text",
    "attachments": [
      {
        "type": 1,
        "name": "text",
        "contents_base64": "text"
      }
    ],
    "usage": 1,
    "body_template_base64": "text",
    "scope": 1,
    "entity_ids": [
      "text"
    ]
  }
}

Add a new email template, including a subject line template, body template, and any attachments. See Custom Templates for template usage and placeholders.

Converting to Base64

The body template and any image attachments are expected as base64-encoded strings. Most environments provide a simple method to encode an HTML file, for example:

Platform
Command

Mac

base64 -i template.html -o base64.txt

Linux

base64 template.html > base64.txt

PowerShell

[Convert]::ToBase64String([IO.File]::ReadAllBytes("./template.html")) > base64.txt

Example Request

curl "https://{{VEZA_URL}}/api/preview/notifications/email_templates" \
-H 'authorization: Bearer '$token \
-d @reminder_with_attachment.json
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:

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

Get email notification template

get
Authorizations
Path parameters
idstringRequired
Responses
200
OK
application/json
get
GET /api/preview/notifications/email_templates/{id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Accept: */*

{
  "value": {
    "id": "text",
    "name": "text",
    "subject_template": "text",
    "body_template": "text",
    "attachments": [
      {
        "type": 1,
        "name": "text",
        "contents_base64": "text"
      }
    ],
    "usage": 1,
    "body_template_base64": "text",
    "scope": 1,
    "entity_ids": [
      "text"
    ]
  }
}

Returns a single template, by id.

Update email template

put
Authorizations
Path parameters
value.idstringRequired
Query parameters
update_maskstring · field-maskOptional
Body
idstringRead-onlyOptional
namestringOptional
subject_templatestringOptional
body_templatestringOptional
usageinteger · enumOptional
body_template_base64stringOptional
scopeinteger · enumOptional
entity_idsstring[]Optional
Responses
200
OK
application/json
put
PUT /api/preview/notifications/email_templates/{value.id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 202

{
  "name": "text",
  "subject_template": "text",
  "body_template": "text",
  "attachments": [
    {
      "type": 1,
      "name": "text",
      "contents_base64": "text"
    }
  ],
  "usage": 1,
  "body_template_base64": "text",
  "scope": 1,
  "entity_ids": [
    "text"
  ]
}
{
  "value": {
    "id": "text",
    "name": "text",
    "subject_template": "text",
    "body_template": "text",
    "attachments": [
      {
        "type": 1,
        "name": "text",
        "contents_base64": "text"
      }
    ],
    "usage": 1,
    "body_template_base64": "text",
    "scope": 1,
    "entity_ids": [
      "text"
    ]
  }
}

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

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).

Delete email template

delete
Authorizations
Path parameters
idstringRequired
Responses
200
OK
application/json
Responseobject
delete
DELETE /api/preview/notifications/email_templates/{id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Accept: */*

{}

Delete an email template by id. A successful response will be empty {}.

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

Field
Type
Description

to

Array of strings

List of recipient email addresses

bcc

Array of strings

list of BCC recipient email addresses

cc

Array of strings

list of CC recipient email addresses

template

Notification template object

Sends an email with the specified template or current template.id or template.usage.

default

boolean

if True, use the system default template for the template.usage

Test a new template

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

Note that the HTML template must be converted to a base64-encoded string. Replace template.txt with the path to the actual template file.

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

When default is true, the email uses the original Veza-provided template for a valid 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

When default is false or not provided, the email uses the current template for a valid 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"

Attachments

Email templates can include image attachments up to 64KB in size. Attachments must be base64-encoded and included in the attachments array when creating or updating templates.

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.

Attachment Schema

Field
Type
Description

type

AttachmentType

Optional attachment type.

name

string

Attachment name.

contents_base64

string

Base64-encoded contents.

Valid EmailTemplateAttachmentType values:

  • IMAGE (default)

Using Attachments in Templates

To reference uploaded attachments in your HTML template:

<img src="cid:attachment_name" alt="Description">

Template Usage Types

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.

See Default Notifications Events for all usages and default message content.

Access Review Usage Types

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

Usage Value
Setting
Notes

ACCESS_WORKFLOW_REVIEWER_CHANGED

When a certification row has been reassigned

Sent to all newly added reviewers, and old removed reviewers. Not sent when auto-assigning upon creation, or for changes in draft certifications.

ACCESS_WORKFLOW_STARTED

When a certification has been started

Sent to all reviewers in a single email, when the certification is published

ACCESS_WORKFLOW_COMPLETED

When a certification has been completed

Not sent for expiring certifications

ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY

If no changes have been made

Sent to all inactive reviewers.

ACCESS_WORKFLOW_REMINDER_DUE

When a certification is due

Sent before, the day of, or after the due date.

ACCESS_WORKFLOW_DIGEST_NOTIFICATION

Digest email settings

Periodic summary of in-progress reviews sent based on configured frequency.

Lifecycle Management Usage Types

For a complete list of Lifecycle Management usage types and their descriptions, see LCM Notification Templates.

Placeholders

Placeholders: The message can use different placeholders depending on the usage. See Placeholders for more information about possible placeholders.

Templates support dynamic placeholders that are replaced with actual values when emails are sent. Available placeholders vary by usage type.

Common Placeholders

Placeholder
Description

{{WORKFLOW_NAME}}

Name of the workflow or certification

{{WORKFLOW_URL}}

URL to access the workflow

{{ENTITY_NAME}}

Name of the affected entity

{{ENTITY_TYPE}}

Type of the affected entity

For a complete list of placeholders by usage type, see the Placeholders documentation.

Email Delivery Notes

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.

Error Handling

The API returns standard HTTP status codes and detailed error messages:

  • 200 - Success

  • 400 - Bad Request (invalid parameters)

  • 401 - Unauthorized (invalid API key)

  • 404 - Not Found (template doesn't exist)

  • 409 - Conflict (template with usage already exists)

Rate Limits

API requests are subject to rate limiting. When the limit is exceeded, the API returns a 429 Too Many Requests status code with retry-after headers.

PreviousNotification TemplatesNextTeam and User Management APIs

Last updated

Was this helpful?