Skip to main content

Customer Managed SendGrid Setup

This runsheet works a customer through the required steps to setup SendGrid for each of their brands.

Inputs​

  • Customer has already setup a SendGrid Account

Tasks​

API Key​

The API Key is a critical piece of configuration to allow HaaS to connect to your SendGrid account. At a minimum, you should create a production and non-production API Key to segregate the CDR and non CDR facing HaaS instances. You do not need to create a separate API Key for each brand within a space, but you may do so if you wish.

Steps:

From Address​

The from address given to HaaS is the email address that all HaaS notifications will be sent as. An email like cdr@exampleholder.com works well for this purpose or any other automated mail address that your customers have seen from your systems already. This can be set per brand.

warning

It is imperative that you check that SendGrid domain authentication is successfully configured for each from address domain to reduce the likelihood that the emails will be filtered as spam. You can check this in the Sender Authentication section in the SendGrid console, where there should be a verified line in Domain Authentication for the domain.

If the domain authentication is not yet setup, setting it up is a specialised task and requires the assistance of your DNS administrator. https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication

Template Setup​

The templates required align to the event types in the adapter sendNotification endpoint, but HaaS does the heavy lifting of converting the user and account IDs to human friendly names appropriate for email content.

The SendGrid dynamic templates allow customer control of email branding in a way completely separate from HaaS. The active version of a template can be changed without affecting the template ID, allowing for templates to be upgraded and rolled back to previous versions if an issue is detected.

There is a specific JSON payload for each event type which HaaS will send to the sendMail SendGrid API as a data template data payload. The following sections will describe the JSON payload for each event and a sample template for each.

https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates#design-a-dynamic-template

The template ID can be found by expanding the template in the dynamic template list. Copy each one of these template IDs into the relevant template ID in your HaaS configuration. SendGridTemplateId. You will probably need to create a new template per event per brand so that you can control the styling of each email per brand.

info

All template examples are demonstrated using https://mjml.io, a lightweight JavaScript framework designed to help create responsive email-friendly HTML content. Whilst using MJML is used here for example purposes, you're not required to use it - you are free to create templates using any method or tool you prefer.

To preview the output, visit https://mjml.io, click "Try it live" on the homepage, and paste the template code into the editor.

info

The event payloads in the sections below include some banking-specific scenarios. For energy-specific notifications, the items in the accountDetails array have the following structure where:

  • maskedAccountNumber is the energy account number
  • accountNickname is the energy account address
{
"maskedAccountNumber": "18270047",
"accountNickname": "43 Albacore Crescent, Burradoo NSW 2576",
"nmis": [
"94F48C99-A864-464F-B9DC-095413D5E2F9"
]
}

Arrangement Action​

  • Subject:
CDR Arrangement {{ arrangementAction }}
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"adr": "Test Software Product",
"arrangementAction": "STARTED",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
{{#equals arrangementAction "STARTED"}}
CDR Arrangement Started
{{/equals}}
{{#equals arrangementAction "AMENDED"}}
CDR Arrangement Amended
{{/equals}}
{{#equals arrangementAction "REVOKED"}}
CDR Arrangement Revoked
{{/equals}}
{{#equals arrangementAction "EXPIRED"}}
CDR Arrangement Expired
{{/equals}}
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{#equals arrangementAction "STARTED"}}
{{ sender }} has set-up a sharing arrangement with {{ adr }} and is sharing data from one or more of your accounts:
{{/equals}}
{{#equals arrangementAction "AMENDED"}}
{{ sender }} has amended an existing sharing arrangement with {{ adr }} and is sharing data from one or more of your accounts:
{{/equals}}
{{#equals arrangementAction "REVOKED"}}
An existing sharing arrangement for {{ adr }} was revoked on request by {{ sender }} for one or more of your joint accounts:
{{/equals}}
{{#equals arrangementAction "EXPIRED"}}
An existing sharing arrangement for {{ adr }} has expired for one or more of your joint accounts:
{{/equals}}
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Sharing Disabled​

  • Subject:
CDR Data Sharing Disabled
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
Data Sharing Disabled
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{ sender }} has disabled all current and future data sharing from one or more of the account(s) you share:
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
<mj-text>
If you have setup data sharing arrangements with Accredited Data Recipients you may receive notifications of their cancellation.
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Sharing Requested​

  • Subject:
CDR Data Sharing Requested
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"requestExpiration": "2022-08-01 10:30 +10.00",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
Data Sharing Requested
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{ sender }} has requested that Data Sharing be enabled on the following joint account(s):
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
<mj-text>
In order for this request to proceed, all account holders, must approve the request by {{ requestExpiration }} . <br />
</mj-text>
<mj-text>
To manage this request please goto Data Sharing > Account Permissions within internet banking.
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Sharing Request Action One​

  • Subject:
CDR Data Sharing Approved
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"requestExpiration": "2022-08-01 10:30 +10.00",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
Data Sharing Approved
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{ sender }} has approved the request to enable data sharing on the following joint account(s):
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
<mj-text>
Data Sharing will only be enabled if all account holders approve the request by {{ requestExpiration }}.
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Sharing Request Complete​

  • Subject:
CDR Data Sharing Request {{ action }}
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"action": "APPROVED",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:

<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
{{#equals action "APPROVED"}}
Data Sharing Enabled
{{/equals}}
{{#equals action "DENIED"}}
Data Sharing Request Denied
{{/equals}}
{{#equals action "EXPIRED"}}
Data Sharing Request Expired
{{/equals}}
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{#equals action "APPROVED"}}
All account holders have approved the request to enable data sharing from the following account(s):
{{/equals}}
{{#equals action "DENIED"}}
{{ sender }} has denied your request to enable data sharing for the following account(s):
{{/equals}}
{{#equals action "EXPIRED"}}
Your request to enable data sharing for the following account(s) has expired:
{{/equals}}
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
<mj-text>
{{#equals action "APPROVED"}}
All account holders will now be able to share data from these account(s) at any time.
{{/equals}}
{{#equals action "DENIED"}}
This means that all data sharing will remain disabled for these account(s) and no further action will be taken.
{{/equals}}
{{#equals action "EXPIRED"}}
This means that all data sharing will remain disabled for these account(s) and no further action will be taken.
{{/equals}}
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Secondary User Instruction Action​

  • Subject:
Secondary User Instruction {{ action }}
  • Event:
{
"name": "Joe Bloggs",
"sender": "Mark Smith",
"secondaryName": "Alice Accountant",
"action": "ADDED",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
{{#equals action "ADDED"}}
Secondary User Instruction Added
{{/equals}}
{{#equals action "REMOVED"}}
Secondary User Instruction Removed
{{/equals}}
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{#equals action "ADDED"}}
{{sender}} has provided an instruction to enable data sharing for a secondary user, {{secondaryName}}, for one or more of your account(s):
{{/equals}}
{{#equals action "REMOVED"}}
{{#equals sender "SYSTEM"}}
An instruction to enable data sharing for a secondary user, {{secondaryName}}, has been removed for one or more of your account(s):
{{else}}
{{sender}} has removed an instruction to enable data sharing for a secondary user, {{secondaryName}}, for one or more of your account(s):
{{/equals}}
{{/equals}}
</mj-text>
<mj-text>
<ul>
{{#each accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</mj-text>
<mj-text>
{{#equals action "ADDED"}}
{{secondaryName}} will establish data sharing arrangements from your account(s).
{{/equals}}
{{#equals action "REMOVED"}}
{{secondaryName}} will no longer be able to share data from your account(s).
{{/equals}}
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Periodic Summary​

  • Subject: CDR Activity Summary
  • Event:
{
"name": "Joe Bloggs",
"period": "WEEKLY",
"sharingEvents": [
{
"type": "STARTED",
"actor": "Mark Smith",
"timestamp": "2022-08-01 10:30 +10.00",
"adr": "Test Software Product",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
]
}
],
"secondaryUserInstructions": [
{
"type": "ADDED",
"actor": "Mark Smith",
"timestamp": "2022-08-01 10:30 +10.00",
"secondaryName": "Alice Accountant",
"accountDetails": [
{ "maskedAccountNumber": "XXXX5685", "accountNickname":"Account 1"},
{ "maskedAccountNumber": "XXXX5487", "accountNickname":"Account 2"}
]
}
],
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:

<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
CDR Activity Summary
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
{{#equals period "WEEKLY"}}
Here’s a summary of the CDR data sharing events that happened during the past week.
{{/equals}}
{{#equals period "MONTHLY"}}
Here’s a summary of the CDR data sharing events that happened during the past month.
{{/equals}}
</mj-text>
<mj-text>
<table>
{{#each sharingEvents}}
<tr><td>
{{#equals this.type "STARTED"}}
On {{this.timestamp}} {{this.actor}} started sharing with {{this.adr}} on account(s):
{{/equals}}
{{#equals this.type "AMENDED"}}
On {{this.timestamp}} {{this.actor}} amended an existing sharing arrangement with {{this.adr}} on account(s):
{{/equals}}
{{#equals this.type "REVOKED"}}
On {{this.timestamp}} {{this.actor}} revoked an existing sharing arrangement with {{this.adr}} on account(s):
{{/equals}}
{{#equals this.type "EXPIRED"}}
On {{this.timestamp}} a sharing arrangement with {{this.adr}} expired on account(s):
{{/equals}}
<ul>
{{#each this.accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</td></tr>
{{/each}}
{{#each secondaryUserInstructions}}
<tr><td>
{{#equals this.type "ADDED"}}
On {{this.timestamp}} {{this.actor}} provided a secondary user instruction for {{ this.secondaryName }} on account(s):
{{/equals}}
{{#equals this.type "REMOVED"}}
On {{this.timestamp}} {{this.actor}} removed a secondary user instruction for {{ this.secondaryName }} on account(s):
{{/equals}}

<ul>
{{#each this.accountDetails}}
<li>{{this.maskedAccountNumber}} - {{this.accountNickname}}</li>
{{/each}}
</ul>
</td></tr>
{{/each}}
</table>
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

OTP​

  • Subject:
CDR Sharing One Time Password
  • Event:
{
"name": "Joe Bloggs",
"otpValue": "123455",
"otpExpiry": "10 minutes",
"dashboardUrl": "https://dashboard.exampleholder.com"
}
  • Sample Template:
<mjml>
<mj-head>
<mj-attributes>
<mj-class name="h1" font-size="30px" />
</mj-attributes>
</mj-head>
<mj-body>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text mj-class="h1">
CDR Data Sharing One Time Password
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text>Hi {{name}}</mj-text>
<mj-text>
Your One Time Password for CDR Data Sharing is {{otpValue}}. It will expire in {{otpExpiry}}.
</mj-text>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column>
<mj-text> What is CDR data sharing?</mj-text>
<mj-text>The Consumer Data Right is an Australian government initiative to enable the secure transfer of data held by us to accredited parties (Accredited Data Recipients).</mj-text>
<mj-text>To manage your data sharing settings please goto: <a href="{{ dashboardUrl }}">{{ dashboardUrl }}</a></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>

Outputs​

  • The API Key, From Address and Template IDs for the brands of a haas space.