Email Templates

Owned by Joel Morgan Kearney (Unlicensed)
Last updated: Aug 07, 2023 by Joel Kearney
12 min read

The Email Templates API is used to access, create, and modify the email template objects on your business' account. The Email Templates API is connected to the Email Categories API, as email templates are grouped into different email categories.

Email templates in email categories where allowDuplicates is set to false

On every email template, you will see that it falls into an email category from the property emailCategory. In the email category object, you'll see an allowDuplicates property. If that property is set to false, then the email templates in that category must follow the level rules outlined in the table below. Email templates are each assigned a level of 0-4 that returns filled in the level property.

LevelDescription
0Default template provided by the server - businessId property would be set to null; if editing the default template with level set to 0, you'll want to call the endpoint to create a new template with the businessId set to your own and the level set to 1; level 0 templates cannot not be edited directly and there cannot be more than one level 0 template per category.
1

Default template in the category that has been edited by the business - businessId property is filled in with the business’s unique numeric ID (no services/classes or languages have been applied). There cannot be more than one template in an email category where allowDuplicates is false with its level set to 1. There is also a front-end check on our backoffice to ensure that there is only 1 template with a templateName of "Default Template". We strongly recommend that any new templates you create at subsequent levels (level 2, 3, or 4) have a different name than "Default Template".

This template acts as a fall back if there is not a template that matches the appointment's selected reason (level 3), or the client for the appointment's assigned language (level 2), or a combination of the two (level 4).

2Template that has a language applied to it but no reasons applied to it. There cannot be more than one template per category at level 2 with the same language assigned to it and no reasons. For instance, you could not have two appointment reminder templates set to level 2 that are set to a language of 'es', or Spanish
3Template that has one or more reasons applied to it but no language applied to it. This would mean that the template's reasonIdList property is filled out with the array of reasonIds that you want the template to apply to. Only one template per category per reason can be created at level 3. For instance, if you have a service called "Consultation" with a reasonId of 12345, you could not create 2 templates in any one category where allowDuplicates is false that is set to a level 3 and both have reasonId 12345 in the reasonIdList. The backend will reject this if you try to save with that. Even if you are creating the template and trying to assign both Consultation and another service (say "Follow up Meeting") to the same template, if it is set to level 3 and you already have Consultation stored in another template in that category, your update will not take.
4

Template that has both a language and one or more reasons applied to it. Only one template per category can be created which matches both the language and any reason in the reasonIdList property.

You could, for instance, have two templates in the same category where both languages was set to 'es', or Spanish, so long as their reasonIdLists did not contain any of the same reasonIds. Alternatively, you could have two templates in the same category where both the reasonIdLists are the same so long as their languages differ. In both these instances, the level property would need to be set to 4 in order for the logic to work in hierarchical order to send these emails out over the default template if the client matched the language preference and the appointment matched one of the reasonIds.

On this page




Email Templates API Endpoints

Return to Top

These are the endpoints that are available under the /emailTemplates path, which lists all the different email templates on your business' account.

EndpointDescription
GET /emailTemplates/emailCategory/{emailCategoryId}Returns all email template objects within specified email category in array format.
GET /emailTemplates/{emailTemplateId}Returns a JSON object for specified email template.
GET /emailTemplates/objectType/{objectType}Returns all email template objects with specified objectType in array format.
POST /emailTemplates

Creates a new email template object on an account.

Request body/payload: Must pass an email template object in request body/payload. 

For these calls, you need to pass an email template object with all required fields and any fields you want to set or update filled in the body of the payload. We have an example of a email template object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

POST /emailTemplates/{emailTemplateId}/merged

Returns specified email template object to display to the user to edit before sending to selected clients.

Request body: Must pass an email template object in request body/payload. 

For these calls, you need to pass an email template object with the businessId, emailTemplateId, parameterMap, and professionalId fields set in the body of the payload. We have an example of a email template object in the responses section below.

PUT /emailTemplates/{emailTemplateId}

Updates an existing email template object.

Request body/payload: Must pass an email template object in request body/payload.

For these calls, you need to pass an email template object with all required fields and any fields you want to update filled in the body of the payload. We have an example of an email template object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

DELETE /emailTemplates/{emailTemplateId}Removes an email template object from view by setting its active property to false.



Email Templates API Parameters

Return to Top

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. 

ParameterTypeEndpoints to be used withDescription
staffIdintegerGET /emailTemplates/{emailTemplateId}Should be set as the ID of any staff connected to email template objects to be returned following a GET call. 
reasonIdintegerGET /emailTemplates/{emailTemplateId}Should be set as the ID of any reason connected to email template objects to be returned following a GET call.



Email Templates API Request Body/Payload


The objects below represent the minimum viable objects to pass that are needed to create or update an emailTemplates object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

POST /emailTemplates 
{
    "active": true,
    "addressCountsInvalid": false,
    "allowOnline": false,
    "attachFileLibraryUUids": ["d0d6eaf895bf458da1a1d0294a0eb4ff"],
    "bccAddress": null,
    "bccAddressCharCountInvalid": false,
    "businessId": 43111,
    "ccAddress": null,
    "ccAddressCharCountInvalid": false,
    "createdDate": 1539263813076,
    "createdUser": "MORGANKEARNEY",
    "emailBecause": "you are a client of %BUSINESS_NAME% and you have cancelled your previously scheduled appointment through our online tool.<br/>",
    "emailBody": "(HTML coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 72042,
    "externalName": null,
    "filesForDisplay": [{fileName: "Share-Links.png", fileLibraryUUID: "d0d6eaf895bf458da1a1d0294a0eb4ff"}],
    "fromAddress": "noreply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "languageObject": {languageCode: null, name: "None"},
    "level": 3,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": "MORGANKEARNEY",
    "noHeader": null,
    "reasonIdList": [646892],
    "reasonNameList": null,
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": "43111/templates/template-12-72042.html",
    "sortOrder": null,
    "subject": "[Appointment Cancellation] %PROFESSIONAL_FULLNAME% on %APPT_DATE_TIME%",
    "templateName": "Clone of Default Template",
    "toAddress": "%CLIENT_EMAILADDRESS%",
    "toAddressCharCountInvalid": false,
    "toName": "%CLIENT_FULLNAME%"
}
PUT /emailTemplates 
{
    "active": true,
    "addressCountsInvalid": false,
    "allowOnline": false,
    "attachFileLibraryUUids": ["d0d6eaf895bf458da1a1d0294a0eb4ff"],
    "bccAddress": null,
    "bccAddressCharCountInvalid": false,
    "businessId": 43111,
    "ccAddress": null,
    "ccAddressCharCountInvalid": false,
    "createdDate": 1679420243708,
    "createdUser": "MORGANKEARNEY",
    "emailBecause": " you are a client of %BUSINESS_NAME% and you have cancelled your previously scheduled appointment through our online tool.<br/>"
    "emailBody": "(HTML coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 215467,
    "externalName": null,
    "filesForDisplay": [{fileName: "Share-Links.png", fileLibraryUUID: "d0d6eaf895bf458da1a1d0294a0eb4ff"}],
    "fromAddress": "noreply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "languageObject": {languageCode: null, name: "None"},
    "level": 3,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": "MORGANKEARNEY",
    "noHeader": null,
    "reasonIdList": [646892],
    "reasonNameList": null,
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": "43111/templates/template-12-215467.html",
    "sortOrder": null,
    "subject": "[Appointment Cancellation] %PROFESSIONAL_FULLNAME% on %APPT_DATE_TIME%",
    "templateName": "Clone of Default Template",
    "toAddress": "%CLIENT_EMAILADDRESS%",
    "toAddressCharCountInvalid": false,
    "toName": "%CLIENT_FULLNAME%"
}



Email Templates API Responses

Return to Top

GET /emailTemplates/emailCategories/{emailCategoryId} 
[{
    "active": true,
    "allowOnline": null,
    "attachFileLibraryUUids": null,
    "bccAddress": null,
    "businessId": 43111,
    "ccAddress": null,
    "createdDate": 1411380040000,
    "createdUser": "Creator",
    "emailBecause": "you are a staff member at %BUSINESS_NAME% and the client did not pay for an appointment.<br/>,
    "emailBody": "(HTML coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 4878,
    "fromAddress": "norply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "level": 0,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "reasonIdList": null,
    "reasonNameList": null,
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": null,
    "subject": "[Appointment Cancellation] %CLIENT_FULLNAME% on %APPT_DATE_TIME%",
    "templateName": "Default Template",
    "toAddress": "%STAFF_EMAIL%",
    "toName": "%STAFF_FULLNAME%"
}]
GET /emailTemplates/{emailTemplateId} 
{
    "active": true,
    "allowOnline": false,
    "attachFileLibraryUUids": null,
    "bccAddress": null,
    "businessId": 43111,
    "ccAddress": null,
    "createdDate": 1538683116843,
    "createdUser": "JoeSchmo",
    "emailBecause": "you are a client of %BUSINESS_NAME% and have a scheduled appointment with %PROFESSIONAL_FULLNAME%.<br/>",
    "emailBody": "(HTML coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 70063,
    "fromAddress": "norply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "level": 3,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": "JoeSchmo",
    "noHeader:" null,
    "reasonIdList": [240127, 159578],
    "reasonNameList": ["Advanced Dog Training", "Bb"],
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": "43111/templates/template-27-70063.html",
    "sortOrder": null,
    "subject": "[Appointment Changed] %PROFESSIONAL_FULLNAME% on %APPT_DATE_TIME%",
    "templateName": "Clone of Default Template",
    "toAddress": "%CLIENT_EMAILADDRESS%",
    "toName": "%CLIENT_FULLNAME%"
}
GET /emailTemplates/objectType/{objectType} 
[{
    "active": true,
    "allowOnline": false,
    "attachFileLibraryUUids": null,
    "bccAddress": null,
    "businessId": 43111,
    "ccAddress": null,
    "createdDate": 1574350510063,
    "createdUser": "MORGANKEARNEY",
    "emailBecause": null,
    "emailBody": "(HTML coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 155556,
    "externalName": null,
    "fromAddress": "noreply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "level": 1,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": "MORGANKEARNEY",
    "noHeader": null,
    "reasonIdList": null,
    "reasonNameList": null,
    "replyToAddress": null,
    "resellerId": 3,
    "s3FileName": "43111/templates/template-68-155556.html",
    "sortOrder": null,
    "subject": null,
    "templateName": "Create an appointment",
    "toAddress": "%STAFF_EMAIL%",
    "toName": "%STAFF_FULLNAME%"
}]
POST /emailTemplates 
{
    "active": true,
    "allowOnline": false,
    "attachFileLibraryUUids": null,
    "bccAddress": null,
    "businessId": 43111,
    "ccAddress": null,
    "createdDate": 1539011086954,
    "createdUser": "JoeSchmo",
    "emailBecause": null,
    "emailBody": "(Displays html coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 70722,
    "externalName": null,
    "fromAddress": "norply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "level": 1,
    "location": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "noHeader": null,
    "reasonIdList": null,
    "reasonNameList": null,
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": "43111/templates/template-63-70722.html",
    "sortOrder": null,
    "subject": "Invoice Summary Of Charges",
    "templateName": "Default Bulk Invoice Template",
    "toAddress": "%CLIENT_EMAILADDRESS%",
    "toName": "%CLIENT_FULLNAME%"
}
PUT /emailTemplates/{emailTemplateId} 
{
    "active": true,
    "allowOnline": null,
    "attachFileLibraryUUids": ["991d5e4a19454d24b003a8a624965b3e"],
    "bccAddress": null,
    "businessId": 43111,
    "ccAddress": null,
    "createdDate": 1538683116843,
    "createdUser": "JoeSchmo",
    "emailBecause": "you are a client of %BUSINESS_NAME% and have a scheduled appointment with %PROFESSIONAL_FULLNAME%.<br/>,
    "emailBody": "(Displays html coding for body of email template)",
    "emailBodyText": null,
    "emailCategory": {Email category object for email category of specified email template - for more info, see email categories API page},
    "emailTemplateId": 70722,
    "fromAddress": "norply@timetap.com",
    "fromName": "%BUSINESS_NAME%",
    "language": null,
    "level": 3,
    "location": null,
    "modifiedDate": 1539278841169,
    "modifiedUser": "JoeSchmo",
    "noHeader": null,
    "reasonIdList": [240127, 240094],
    "reasonNameList": ["Advanced Dog Training", "Dog Training"],
    "replyToAddress": "%PROFESSIONAL_EMAIL%",
    "resellerId": 3,
    "s3FileName": "43111/templates/template-27-70063.html",
    "sortOrder": null,
    "subject": "[Appointment Changed] %PROFESSIONAL_FULLNAME% on %APPT_DATE_TIME%",
    "templateName": "Dog Training Appointment Rescheduled",
    "toAddress": "%CLIENT_EMAILADDRESS%",
    "toName": "%CLIENT_FULLNAME%"
}



Email Templates Object Values

Return to Top

Property NameTypeRequiredDescription
activebooleanYesIndicates whether or not the specified email template should return on GET calls. 
allowOnlineboolean
Indicates whether or not the specified email template is allowed online.
attachFileLibraryUUidsarray
Displays as an array of unique alphanumeric fileLibraryUUids of any files attached to the specified email template.
bccAddressstring
Displays as the Bcc field of the specified email template.
businessIdintegerYesProvides unique numeric ID for the business to which the specified email template belongs.
ccAddressstring
Displays as the CC field of the specified email template.
createdDateinteger
Displays as the date the specified email template was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays the username of user who created the specified email template.
emailBecausestring
Displays as the reason why the specified email template is being sent.
emailBodystringYesDisplays as the body of the specified email template.
emailBodyTextstring
Displays as the text of the body of the specified email template.
emailCategoryobjectYesDisplays the email category object that the specified email template falls within - for more info, see Email Categories API page.
emailTemplateIdintegerYes, on PUT callsProvides unique numeric ID for the specified email template.
externalNamestring
Displays as the external name of the specified email template.
fromAddressstring
Displays as the From Address of the specified email template.
fromNamestring
Displays as the From Name of the specified email template.
languagestring
Displays as an abbreviation of the language used in the specified email template.
levelintegerYesDisplays as the level of the specified email template. More information on the different levels and what they signify can be found on the Messaging page.
modifiedDateinteger
Displays as date the specified email template was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUserstring
Displays the username of user who last modified the specified email template.
noHeaderboolean
Indicates whether or not the specified email template has a header.
reasonIdListinteger
Displays as the IDs of any reasons connected to the specified email template.
reasonNameListstring
Displays as the names of any reasons connected to the specified email template.
replyToAddressstring
Displays as the Reply to Address of the specified email template.
resellerIdinteger
Provides unique numeric ID for reseller of the specified email template.
s3FileNamestring

Displays as the location/name of the specified email template file as stored in Amazon Web Services repository.

This value cannot be overwritten with any PUT or POST calls.

sortOrderinteger
Affects the order in which the different email templates on the account appear.
subjectstring
Displays as the Subject of the specified email template.
templateNamestring
Displays as Template Name of the specified email template.
toAddressstringYesDisplays as the To address of the specified email template.
toNamestring
Displays as the To name of the specified email template.