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.

• Create email notification template

  • Attachment

  • Usage

• Delete email template

• Get email notification template

• List email templates

• Update email template

• Test email template

  • Test a new template

  • Test an existing template

  • Test the default template for a usage

  • Test the current template for a usage

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.

Create email notification template

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

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

Body parameters:

Name	Type	Description
id	string	Template unique ID (read-only).
name	string	Template name.
subject_template	string	Template to use for the email subject.
body_template_base64	string	Base64-encoded body template.
body_template	string	Body template (deprecated).
attachments	Attachment array	See Attachments below.
usage	Usage enum	See Usage below.

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:

Mac	base64 -i template.html -o base64.txt
Linux	base64 template.html > base64.txt
PowerShell	[Convert]::ToBase64String([IO.File]::ReadAllBytes("./template.html")) > base64.txt

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

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

Name	Type	Description
type	AttachmentType	Optional attachment type.
name	string	Attachment name.
contents_base64	string	Base64-encoded contents.

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.

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

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

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:

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.

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:

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_base_64, name, usage, and subject_template.

Note that the HTML template must 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"