Email templates
The Teamwire backend sends out emails on various occasions, e.g. when a user registers she will be sent an email with a confirmation link in it. Email templates allow to customize the text of these and other emails.
Manage email templates
Return a list of all email templates or details about a particular email template
GET /v<api_version>/admin/templates/<organisation_id>/
GET /v<api_version>/admin/templates/<type>/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_settings permission.
- Admins can request email templates of their own organisation only.
- Superadmins can request email templates of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| type | String | Yes | All admins | The email template type to retrieve. Call this endpoint without URL parameters to obtain a list of valid types. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to retrieve the email template for. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the email template(s) is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified that does not match the admin’s organisation and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because either a.) an invalid email template type was specified or b.) the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
If an email template type was specified and the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
content |
String | All admins | The contents of the email template. The template uses Jinja syntax for placeholders that depend upon the particular email template type. |
If no email template type was specified and the request was successful, the JSON structure returned will be an array of JSON objects with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
type |
String | All admins | The email template type. This can be used in successive requests to retrieve details about a particular email template. |
label |
String | All admins | A verbose label in English language describing the email template’s purpose. This can be used for display purposes. |
Update an email template
PUT /v<api_version>/admin/templates/<organisation_id>/
PUT /v<api_version>/admin/templates/<type>/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_settings permission.
- Admins can update email templates of their own organisation only.
- Superadmins can update email templates of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| *api_version * | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | No | All admins | The ID of the organisation to update the email template for. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
type |
String | No | All admins | The email template type to update. Call the GET endpoint without URL parameters to obtain a list of valid types. |
content |
String | No | All admins | The email template’s new contents. The template uses Jinja syntax for placeholders that depend upon the particular email template type. The syntax will be validated when updating. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the updated email template is returned as a JSON object as described for the GET request. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified that does not match the admin’s organisation and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because either a.) an invalid email template type was specified or b.) the organisation could not be found. |
| 409 (Conflict) | The request failed because either a.) the organisation has been disabled or b.) the email template’s contents triggered an error during validation. |
Preview email templates
Render a preview of an email template
POST /v<api_version>/admin/template_preview/<type>/
This endpoint can be used to render a preview of the specified email template type using the supplied template contents, thus allowing a user to preview what a sent email would look like while at the same time validating the template contents e.g. for correct Jinja placeholder syntax.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| type | String | No | All admins | The email template type for which a preview is to be generated. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
template |
String | No | All admins | The email template’s contents to use for rendering the review. The template uses Jinja syntax for placeholders that depend upon the particular email template type. The syntax will be validated before generating the preview. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The rendered email is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the calling admin’s organisation has been disabled. |
| 404 (Not found) | The request failed because an invalid email template type was specified. |
| 409 (Conflict) | The request failed because the email template’s contents triggered an error during validation. |
If the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
subject |
String | All admins | The subject for the example email generated using the specified email template. |
body |
String | All admins | The body of the example email generated using the specified email template. |