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

bearerAuth

AuthorizationstringRequired

Bearer token authentication using a Veza Personal API key.

Header Format: Authorization: Bearer <your-api-key>

Creating an API Key:

1. Log into your Veza tenant
2. Navigate to Administration → API Keys
3. Generate a new API key and save the value securely

Responses

200

OK

application/json

default

Default error response

application/json

get

/api/preview/notifications/email_templates

HTTPcURLJavaScriptPython

GET /api/preview/notifications/email_templates HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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

bearerAuth

AuthorizationstringRequired

Bearer token authentication using a Veza Personal API key.

Header Format: Authorization: Bearer <your-api-key>

Creating an API Key:

1. Log into your Veza tenant
2. Navigate to Administration → API Keys
3. Generate a new API key and save the value securely

Body

application/json

Responses

200

OK

application/json

default

Default error response

application/json

post

/api/preview/notifications/email_templates

HTTPcURLJavaScriptPython

POST /api/preview/notifications/email_templates HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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

bearerAuth

AuthorizationstringRequired

Bearer token authentication using a Veza Personal API key.

Header Format: Authorization: Bearer <your-api-key>

Creating an API Key:

1. Log into your Veza tenant
2. Navigate to Administration → API Keys
3. Generate a new API key and save the value securely

Path parameters

idstringRequired

Responses

200

OK

application/json

default

Default error response

application/json

get

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

HTTPcURLJavaScriptPython

GET /api/preview/notifications/email_templates/{id} HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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

bearerAuth

AuthorizationstringRequired

Bearer token authentication using a Veza Personal API key.

Header Format: Authorization: Bearer <your-api-key>

Creating an API Key:

1. Log into your Veza tenant
2. Navigate to Administration → API Keys
3. Generate a new API key and save the value securely

Path parameters

value.idstringRequired

Query parameters

update_maskstring · field-maskOptional

Body

application/json

idstringRead-onlyOptional

namestringOptional

subject_templatestringOptional

body_templatestringOptional

usageinteger · enumOptional

body_template_base64stringOptional

scopeinteger · enumOptional

entity_idsstring[]Optional

Responses

200

OK

application/json

default

Default error response

application/json

put

/api/preview/notifications/email_templates/{value.id}

HTTPcURLJavaScriptPython

PUT /api/preview/notifications/email_templates/{value.id} HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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

bearerAuth

AuthorizationstringRequired

Bearer token authentication using a Veza Personal API key.

Header Format: Authorization: Bearer <your-api-key>

Creating an API Key:

1. Log into your Veza tenant
2. Navigate to Administration → API Keys
3. Generate a new API key and save the value securely

Path parameters

idstringRequired

Responses

200

OK

application/json

Responseobject

default

Default error response

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /api/preview/notifications/email_templates/{id} HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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.

Access Security Usage Types

Usage Value	Description
ASSESSMENT_RULE	Sent when a rule is triggered based on query results meeting configured conditions
ASSESSMENT_RISK	Sent when risks are identified by a saved query with risk notifications enabled

For placeholders and default templates for these usage types, see Access Security 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.