# Templates

## Templates

We support the following templates:

**Consents API**

* [Confirmation of changes](#confirmation-of-changes)
* [User created](#user-created)
* [Validation - Approval - File](#validation-approval-signature)
* [Validation - Approval - Signature](#validation-approval-signature)
* [Validation - Double opt-in](#validation-double-opt-in)

**Preference Management Platform**

* [Authentication - Magic Link](#authentication-magic-link)
* [Authentication - One-Time Password](#authentication-one-time-password)

**Privacy request module**

* [Access Data Request fulfillment notification](#access-data-request-fulfillment-notification)
* [Delete Data Request fulfillment notification](#delete-data-request-fulfillment-notification)
* [Identity verification](#identity-verification)
* [Opt out Data request fulfillment notification](#opt-out-request-fulfillment-notification)
* [Refusal notification](#refusal-notification)
* [Work in progress notification](#work-in-progress-notification)

## **Consents API**

### Confirmation of changes

Template ID: `confirm-consent-changed`

Send a confirmation email to let users know that their changes have been correctly taken into account.

#### Parameters

No parameters are provided when sending a confirmation of changes email.

### User created

Template ID: `consents-user-created`

Send a welcome message to the user with an authenticated link to the Preference Center when the user is created through their first consent event.

#### Parameters

The following parameters are provided to the template when sending a welcome message:

| Name                 | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `privacy_center_url` | URL of the Preference Center with a valid consent token. |

### Validation - Approval - File

Template ID: `validation-approval-file`

Approval request for confirming changes to a user consent status from an event that uses the `file` validation method. Approval requests are similar to double opt-in but are intended to be processed internally, while double opt-in is a confirmation from the end-user directly.

#### Parameters

The following parameters are provided to the template when sending an approval email:

| Name                     | Description                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user for approving consent choices. This should be used as the URL for a link or button in the email. |

### Validation - Approval - Signature

Template ID: `validation-approval-signature`

Approval request for confirming changes to a user consent status from an event that uses the `signature` validation method. Approval requests are similar to double opt-in but are intended to be processed internally, while double opt-in is a confirmation from the end user directly.

#### Parameters

The following parameters are provided to the template when sending an approval email:

| Name                     | Description                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user for approving consent choices. This should be used as the URL for a link or button in the email. |

### Validation - Double opt-in

Template ID: `validation-double-optin`

Collect double opt-in for a consent event that uses the `email` validation method.\
This allows users to confirm their choices before a consent event is stored.

#### Parameters

The following parameters are provided to the template when sending a double opt-in email:

| Name                     | Description                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user to confirm their consent choices. This should be used as the URL for a link or button in the email. |

### Metadata from consents events to email templates

Didomi allows you to use `metadata` attached to the consent events created from the API in the email sent to the end-user. By adding metadata to the consent event, you can include a custom parameter in the template to access the information recorded during consent.

#### Add metadata reference in Consent event

```json
POST /consents/events?organization_id={organization_id}

{
  "user": {
    "organization_user_id": "user@domain.com",
    "metadata": {
      "redirect_url": "https://google.com"
    }
  },
  "consents": {
    "purposes": [
      {
        "id": "purpose_id",
        "enabled": true
      }
    ]
  }
}
```

#### Add parameter in the email template

To add a metadata parameter in the email template, construct the parameter using the following format:

```
{{metadata_PROPERTY_IN_METADATA}}
```

And add this parameter in your email template:

```json
POST /marketplace/emails?organization_id=YOUR_ORGANIZATION_ID

{
    "type_id": "didomi", 
    "email_type": "validation-double-optin",
    "properties": {
        "html": "<html>\n<head>\n<title>Privacy Center Approval</title>\n
                </head>\n<body>\n<div>\nCliquez ici pour confirmer votre 
                consentement: <a href=\"{{validation_approve_url}}
                &redirect_url={{metadata_redirect_url}}\">{{validation_approve_url}}
                </a>\n</div>\n</body>\n</html>"
    }
}
```

## Preference Management Platform

### Authentication - Magic Link

Template ID: `privacy-center-auth`

Send an authentication link to users when they access a Preference Center without a valid consent token. The email allows users to confirm their identity and access a Preference Center for the associated email address.

#### Parameters

The following parameters are provided to the template when sending a Magic Link authentication email:

| Name                 | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `privacy_center_url` | URL of the Preference Center with a valid consent token. |

### Authentication - One-Time Password

Template ID: `privacy-center-auth-otp-code`

Send a 6-digit code to users when they access a Preference Center without a valid consent token. The email allows users to receive a code to submit for accessing a Preference Center for the associated email address.

#### Parameters

The following parameters are provided to the template when sending a One-Time password authentication email:

<table data-header-hidden><thead><tr><th width="373">Name</th><th></th></tr></thead><tbody><tr><td>Name</td><td>Description</td></tr><tr><td><code>code</code></td><td>6-digit code to submit in the widget.</td></tr></tbody></table>

## Privacy request module

### Access Data Request fulfillment notification

ID: `request-status-fulfilled-access-my-data`

Send an email to the end-user after setting the status of an **access data request** to `fulfilled`.

To populate the `download_link` variable, you need to add `download_link` property under `extra_message_variables` while [updating](https://developers.didomi.io/api-and-platform/privacy-requests/requests#update-a-request) the related request.

| Type            | Description                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `download_link` | Link that redirects users on a webpage to access or download their data. This should be used as a button or a link. |

### Delete data request fulfillment notification

ID: `request-status-fulfilled-delete-my-data`

Send an email to the end-user after setting the status of a **delete data request** to `fulfilled`.

| Type               | Description                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_right_label` | Right expressed by the end-user while submitting the privacy request. This should be used as a label or a title to recall the right the end-user has submitted. |

### Identity verification

ID: `request-verify`

Send an email to the end-user after a privacy request is submitted in order to validate identity. The request must be created with an [approval workflow](https://developers.didomi.io/api-and-platform/privacy-requests/requests#create-a-request-with-approval-workflow).

#### Parameters

| Name                | Description                                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_right_label`  | Right expressed by the end-user while submitting the privacy request. This should be used as a label or a title to recall the right the end-user has submitted. |
| `confirmation_link` | Redirection link to validate user identity. This should be used in a button or link.                                                                            |

### Opt out request fulfillment notification

ID: `request-status-fulfilled-opt-out`

Send an email to the end-user after setting the status of an **opt-out request** to `fulfilled`.

| Type               | Description                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_right_label` | Right expressed by the end-user while submitting the privacy request. This should be used as a label or a title to recall the right the end-user has submitted. |

### Refusal notification

ID: `request-status-refused`

Send an email to the end-user after request status has been set to `refused`.

| Type               | Description                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_right_label` | Right expressed by the end-user while submitting the privacy request. This should be used as a label or a title to recall the right the end-user has submitted. |

### User created

Template ID: `consents-user-created`

Send a welcome message to the user with an authenticated link to the Preference Center when the user is created through their first consent event.

#### Parameters

The following parameters are provided to the template when sending a welcome message:

| Name                 | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `privacy_center_url` | URL of the Preference Center with a valid consent token. |

### Validation - Approval - File

Template ID: `validation-approval-file`

Approval request for confirming changes to a user consent status from an event that uses the `file` validation method. Approval requests are similar to double opt-in but are intended to be processed internally, while double opt-in is a confirmation from the end-user directly.

#### Parameters

The following parameters are provided to the template when sending an approval email:

| Name                     | Description                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user for approving consent choices. This should be used as the URL for a link or button in the email. |

### Validation - Approval - Signature

Template ID: `validation-approval-signature`

Approval request for confirming changes to a user consent status from an event that uses the `signature` validation method. Approval requests are similar to double opt-in but are intended to be processed internally, while double opt-in is a confirmation from the end user directly.

#### Parameters

The following parameters are provided to the template when sending an approval email:

| Name                     | Description                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user for approving consent choices. This should be used as the URL for a link or button in the email. |

### Validation - Double opt-in

Template ID: `validation-double-optin`

Collect double opt-in for a consent event that uses the `email` validation method.\
This allows users to confirm their choices before a consent event is stored.

#### Parameters

The following parameters are provided to the template when sending a double opt-in email:

| Name                     | Description                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `validation_approve_url` | URL to redirect the user to confirm their consent choices. This should be used as the URL for a link or button in the email. |

### Work in progress notification

ID: `request-status-wip`

Send an email to the end-user after request status has been set to `work_in_progress`.

| Type               | Description                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_right_label` | Right expressed by the end-user while submitting the privacy request. This should be used as a label or a title to recall the right the end-user has submitted. |

***

Some emails )(such as Authentication emails or Privacy request emails) are already available by default. The other templates mentioned above need to be [created in Didomi APIs](https://developers.didomi.io/integrations/emailing/templates/manage-your-templates).