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 are experimental and 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

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.

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":"U2lnbiBpbiBhdCB7e1dPUktGTE9XX1VSTH19IHRvIGZpbmlzaCByZXZpZXcgYnkgYnkge3tXT1JLRkxPV19DRVJUX0RVRV9EQVRFfX0uCg==",
     "attachments":[
        {
           "type":"IMAGE",
           "name":"logo",
           "contents_base64":" << base64-encoded string <64kb >> "
        }
     ],
     "usage":"ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY"
  }
}

Use base64 -D. to decode the input. In this case, body_template_base64 contains the encoded string Sign in at {{WORKFLOW_URL}} to finish review by by {{WORKFLOW_CERT_DUE_DATE}}.

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

{"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 by {{WORKFLOW_CERT_DUE_DATE}}.", "attachments":[{"type":"IMAGE", "name":"logo", "contents_base64":"string"}], "usage":"ACCESS_WORKFLOW_REMINDER_NO_ACTIVITY"}}

`Attachment`

Name Type Description

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

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 or a result is re-assigned. 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.

Placeholders:The message can use different placeholders depending on the usage. See Usage for more information about 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

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

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

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

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

Update an existing template with a new value. You can push either a full template, or only include the fields to modify.

Request:

curl -X PATCH 'https://{{VEZA_URL}}/api/preview/notifications/email_templates/fb377947-a053-4026-bd4a-091be0761012' \
-H 'authorization: Bearer '$token \
-d '{"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>"}'

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

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

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`

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 8 months ago