| 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 (Mail eXchanger) 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.
| Note |
|---|
SendGrid validation logic will prevent the addition of an admin teammate email address that may already be in use on an existing customer account. This means that customers may need to use email modifiers to invite IQVIA support team members. For more information on modifiers (as ClinSpark also supports their use) see here: User accounts and e-mail modifiers To work around this, we recommend that customers add IQVIA support team members with a modifier in their account that reference the customer name. For example, if the support team member is john.smith@iqvia.com, the ‘teammate email address’ invite in SendGrid should be john.smith+customer@iqvia.com. |
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 ClinSpark might have a from ‘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.
This is accomplished after the SendGrid integration is configured as above. This is documented in full on SendGrid’s site, and Foundry Health IQVIA does not support this SendGrid configuration. But in short, to accomplish this the customer must create this domain name on their end and point the DNS MX record to SendGrid. The MX record should look similar to this:
...
Note: You’ll have to configure a second ‘Verification Subdomain’ too with a similar MX and TXT record in order for sendgrid 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 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:
...
IQVIA configures each ClinSpark instance with its respective registered SendGrid domain
Foundry Health IQVIA engineering will create required API keys to be used by ClinSpark.
| Note |
|---|
Note to |
...
IQVIA support: Once the proper API key has been configured, you must ensure that the webhooks are configured via the SendGrid API |
...
(screenshot below). |
...
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.
...