| Table of Contents |
|---|
Summary
This article focuses on the required configuration of SendGrid to work with ClinSpark.
...
| Info |
|---|
Note: ClinSpark handles system-level notifications (account password reset, MFA, authentication alerts, and lab repeat alerts) using existing AWS SNS capabilities. These system-level messages do not require SendGrid. SendGrid is required for transactional (non-system level) messaging to volunteers and subjects. |
Configuration Process Overview
Much like with Twilio, customers must create and maintain their own SendGrid account. A single paid SendGrid account can be used to support any number of customer ClinSpark instances. Ensuring this customer SendGrid account is a paid, non-free account is a precondition of going live in PROD.
...
DNS MX Records
It is highly recommended to register all expected DNS MX records at the start of the configuration process. For instance, customers will need to have a DNS email for PROD use, such as “clinspark-mail.customer-name.com”, and likely want to test this functionality first in Sandbox and VAL environments. For this, customers might also want to additionally register with SendGrid DNS records such as “clinspark-sandbox-mail.customer-name.com” and “clinspark-val-mail.customer-name.com”. It is better to perform this configuration task all at once in the beginning of setup, so that they will be ready when needed.
Setup Process
Step 1: Customer creates a paid SendGrid account
Customers must create and maintain a paid Email API plan/account with SendGrid.
...
For the best possible support, we suggest our customers use the Pro subscription level that allows for more than one teammate. This allows multiple ‘admin’ teammates that can be setup and added to the account for long term support, both from customer and ClinSpark team.
Step 2: Sharing Credentials with ClinSpark support team
Once an account is created, customers need to submit a support ticket requesting configuration of SendGrid. In this ticket, please provide Admin credentials to the support team using the Teammates feature:
...
In the service desk ticket, customers should request that a member of the engineering support team be added to the account as an admin teammate for support purposes. Due to MFA requirements, these must be named users. We may add additional internal support users if needed, though with the appropriate subscription level, this is cost neutral.
Step 3: Customer DNS Admin provisions a DNS MX record with the Customer-owned ‘Main Domain Name’, enabling its use for email
Emails sent from ClinSpark need to come from a customer-owned non-ClinSpark DNS name, the ‘Main Domain Name’. For example, outgoing mail sent from clinspark might have a from address of “clinspark-mail.customer-dns-name.com”, “http://mail.customer.com ” or “customer-recruiting.com”. The actual DNS name is is up to customers, but there must be a separate DNS name per instance of ClinSpark with SendGrid connectivity.
...
Note: You’ll have to configure a second ‘Verification Subdomain’ too with a similar MX and TXT record in order for sendgrid to accept that you own the domain, see further instructions.
Step 4: Authenticate this domain with SendGrid
This step proves to SendGrid that the user has control of this domain. The instructions for doing this are maintained by SendGrid, and can be accessed through your account. This step must be performed by the customer. It is technical, and typically must be done IT staff who setup the DNS MX record itself.
...
Within SendGrid, here is the sequence of phases to perform this configuration:
Step 4.1: Settings > Sender Authentication
...
Step 4.2: Click ‘Authenticate Your Domain’
...
Step 4.3: Configure Settings for Authentication
...
Step 4.4: Disable Automated Security
...
Last, follow the instructions to verify domain ownership by making the required DNS entries. Optionally sendgrid will propose to add DNS records for a ‘Verification Subdomain’ (e.g., em1234.mail.customer.com). This ‘Verification Subdomain’ is only used for authentication and verification.
Step 4.5: Add MX records to the Main Domain Name
When the domain is verified with a ‘Verification Subdomain’ (e.g., em1234.mail.customer.com), add the MX and TXT record to the Main Domain Name as well (http://mail.customer.com ).
...
(which are similar records you needed to add for the verification of the ‘Verification Subdomain’)
Summary
To summarize Step 3 and 4:
Find / choose a domain name that is not the corporate email domain, since that email domain is usually controlled by your corporate IT e-mail system. It can be a subdomain of your corporate domain “clinspark-mail.customer-dns-name.com”, “http://mail.customer.com ” or an entirely different domain like “customer-recruiting.com”.
Start the Authentication of that domain in Sendgrid. Therefore, 2 DNS domains need to be configured :
‘Main Domain Name’ : em1234.mail.customer.com (where ‘http://mail.customer.com ’ is the Main Domain Name) : MX and TXT record need to be added
‘Verification Subdomain’ : http://mail.customer.com (where ‘http://mail.customer.com ’ is the Main Domain Name) : MX and TXT record need to be added SIMILAR to the em1234.* domain.
When the ‘Verification Subdomain’ is verified, you can use the Main Domain Name for further configuring email in clinspark / sendgrid. At this point, you may forget the ‘Verification Subdomain’ and continue with the next steps.
Step 5: Add a provisional Inbound Parse URL
For the next step (‘Set Webhooks’) to work, a provisional Inbound Parse URL needs to be setup. 2 simple steps for this:
...
You should be set to proceed to the next step. Note: the value for this should be overwritten to https:///emailInbound by the next step. If there is an issue with incoming email, it’s worth checking if this value has been actually overwritten.
Step 6: Foundry Health configures each ClinSpark instance with its respective registered SendGrid domain
Foundry Health engineering will create required API keys to be used by ClinSpark.
Note to Foundry support: Once the proper API key has been configured, you must ensure that the webhooks are configured via the SendGrid API:
...
Troubleshooting
Outbound sending works, viewed email notification works, but inbound emails do not show in ClinSpark
...
This is typically because Automated Security was selected when authenticating the domain. You will need to remove the domain from SendGrid and authenticate it again with Automated Security disabled.
...