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.

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"

PreviousNotification Templates NextTeam and User Management APIs

Last updated 4 months ago

Was this helpful?