Dynamic templates

Create a dynamic template

URL

/dynamic_templates

Method

POST

curl -k -v -F 'data[body]=@<template_path>' -F 'data[name]=<template_name>' \
'https://api.paubox.net/v1/<USERNAME>/dynamic_templates' \
--header 'Authorization: Token token=<API KEY>'
  • Replace <template_path> with the path to the handlebars (.hbs) template file you'd like to upload
  • Replace <template_name> with the name you wish to call your template
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.

Update a dynamic template

URL

/dynamic_templates

Method

PATCH

curl -X PATCH -k -v -F 'data[body]=@<template_path>' -F 'data[name]=<template_name>' \
'https://api.paubox.net/v1/<USERNAME>/dynamic_templates/<id>' \
--header 'Authorization: Token token=<API KEY>'
  • Replace <template_path> with the path to the handlebars (.hbs) template file you'd like to upload
  • Replace <template_name> with the name you wish to call your template
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.
  • Replace <id> with the id of the template you wish to update

Delete a dynamic template

URL

/dynamic_templates

Method

DELETE

curl -X DELETE -k --location --request DELETE 'https://api.paubox.net/v1/<USERNAME>/dynamic_templates/<id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<API KEY>'
  • Replace <template_path> with the path to the handlebars (.hbs) template file you'd like to upload
  • Replace <template_name> with the name you wish to call your template
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.
  • Replace <id> with the id of the template you wish to update

View all your org's dynamic templates

URL

/dynamic_templates

Method

GET

curl -k --location --request GET 'https://api.paubox.net/v1/<USERNAME>/dynamic_templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<API KEY>'
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.

View one of your org's dynamic templates

URL

/dynamic_templates

Method

GET

curl -k --location --request GET 'https://api.paubox.net/v1/<USERNAME>/dynamic_templates/<id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<API KEY>'
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.
  • Replace <id> with your template's ID

Send a dynamically templated message

Sending a dynamically templated email is exactly the same as sending a normal API email, apart from the fact that we're hitting a different endpoint, and we're substituting the values template_name and template_values` for the message content (the content field is omitted from the message field)

URL

/templated_messages

Method

POST

curl --location --request POST 'https://api.paubox.net/v1/<API_USERNAME>/templated_messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<FULL API KEY>' \
--data-raw '{
"data": {
"template_name": <template_name>,
"template_values": <template_values>
"message": {
"recipients": [
"recipient@domain.com"
],
"headers": {
"subject": "Hello from the Paubox Email API",
"from": "sender@verifieddomain.com"
}
}
}
}'
  • Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.
  • Replace <template_name> with the name of the template you created in the 'create template' section.
  • Replace <template_values> with the values you'd like to populate in your template, JSON-formatted

Data parameters

<ul>
<li><strong>data</strong> (object)
<ul>
<li><strong>template_name</strong> (string) The name of your template. must match EXACTLY.</li>
<li><strong>template_values</strong> (string) The values you want to include in your templated message, in a JSON-formatted string</li>
<li><strong>message</strong> (object)
<ul>
<li><strong>recipients</strong> (array) An array of recipients as strings. Each recipient can include a name: &quot;J. Smith &lt;jsmith@host.com&gt;&quot;, or not: &quot;jsmith@email.com&quot;. </li>
<li><strong>bcc</strong> (array, optional) An array of BCC recipient addresses. Each recipient can include a name &quot;J. Smith &lt;jsmith@host.com&gt;&quot;, or not: &quot;jsmith@email.com&quot;.</li>
<li><strong>headers</strong> (object)
<ul>
<li><strong>subject</strong> (string) Message subject.</li>
<li><strong>from</strong> (string) Message &quot;from&quot; address. This must match the verified domain of your API key.</li>
<li><strong>reply-to</strong> (string, optional) reply-to address (if different than &quot;from&quot;). This must match the verified domain of your API key.</li>
<li><strong>List-Unsubscribe</strong> (string, optional) The List-Unsubscribe header provides two methods of unsubscribing users: an email unsubscribe, and a web unsubscribe. One, or both, of these methods may be used. More details <a class="custom-link" href='#list-unsubscribe'>here</a></li>
<li><strong>List-Unsubscribe-Post</strong> (string, optional) Used in conjunction with List-Unsubscribe header. More details <a class="custom-link" href='https://tools.ietf.org/html/rfc8058'>here</a></li>
</ul>
</li>
<li><strong>allowNonTLS</strong> (boolean, defaults to false, optional) Set to true to allow message delivery over non-TLS connections rather than converting the message into a Secure Portal message when a non-TLS connection is encountered. This is not HIPAA-compliant if the message contains PHI. </li>
<li><strong>forceSecureNotification</strong>(boolean, defaults to false, optional) Set to true to force message delivery through a Paubox Secure Message. The recipient will be emailed a pickup notification with a link to a secure message hosted by Paubox rather than the contents of the message itself.</li>
<li><strong>attachments</strong> (array[object], optional) An array of objects representing file attachments.
<ul>
<li><strong>fileName</strong> (string) The filename, including the file extension.</li>
<li><strong>contentType</strong> (string) A <a class="custom-link" href="https://www.freeformatter.com/mime-types-list.html">valid MIME type</a> (e.g. &quot;application/pdf&quot;).</li>
<li><strong>content</strong> (string) Base64 encoded contents of the file.</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>

Example JSON request body

{
"data": {
"template_name": "detailed_test",
"template_values": "{ \"name\": \"Howard\", \"conditional\":\"true\",\"items\":[\"one\",\"two\",\"three\"] }",
"message": {
"recipients": [
"recipient@host.com",
"Recipient Name <recipient2@host.com>"
],
"bcc": ["recipient3@host.com", "Recipient Name <recipient4@host.com>"],
"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>"
},
"allowNonTLS": false,
"forceSecureNotification": false,
"attachments": [
{
"fileName": "hello_world.txt",
"contentType": "text/plain",
"content": "SGVsbG8gV29ybGQ"
}
]
}
}
}

Attachment content should be Base64 encoded. An attachment contentType value should be a valid MIME type.

Success response

Code: 200 Content:

{
"sourceTrackingId": "3d38ab13-0af8-4028-bd45-XXXXXXXXXXXX",
"data": "Service OK"
}

The sourceTrackingId can be used with the messages api to track any dynamically templated email (templated mails are sent as normal messages, and are tracked as such)

Error response

Code: 400 Bad Request` Content:

{
"errors": [
{
"code": 400,
"title": "Error Title",
"details": "Description of error"
}
]
}