Summary
SendGrid is an email service provider with an API that allows deep levels of control and feedback for both bulk and transactional emails.
SendGrid is relied on to support email functionality pertaining to study recruitment workflows and volunteer correspondence. In order to use any of this functionality, a customer-provided paid account must be created, and access shared with Foundry Health in order to perform configuration.
| 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 non-system level messaging to volunteers and subjects. |
Configuration Process Overview
Much like with Twilio, customers must create and own 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 typically a precondition of going live in PROD.
...
...
It is highly recommended to register all expected DNS MX records at the start. So for instance, you will need to have a DNS email for PROD use, such as “clinspark-mail.customer-name.com”, and likely want to test this functionality in Sandbox and VAL environments. You might therefore 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 do these all at once in the beginning so that they will be ready when needed.
Setup Process
Step 1: Customer creates a paid SendGrid account
Free accounts have significant limitations which make them unsuitable for use in Production settings. These include limits to the number of emails sent, and also in the number of users who can access the account.
Since Foundry Health needs at least 2 users to be configured as admin users, we suggest this the Pro subscription level:
...
Step 2: Sharing Credentials with Foundry Health Support
The customer should create a JIRA support ticket requesting configuration of SendGrid. In this ticket, please provide Admin credentials to Foundry Health support using the Teammates feature:
...
Please add stuart.robertson@foundryhealth.com 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. Since we have admin rights, we We may add additional internal support users if needed, though at the suggested 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.
This is easily accomplished after the SendGrid integration is configured as above. This is documented in full on SendGrid’s site, and Foundry Health 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 as followssimlar to this:
...
In the above example, the different parts of the domain name have the following mapping:
...
Step 4.4: Disable Automated Security
...
Last, follow the instuctions on the next page 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.
...
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 ).
Usually you’ll need to add the following records for the main domain:
...
Find / choose a domain name that is not the corporate e-mail email domain, since that e-mail 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.
...
Receiving domain: select your incoming email domain
Destination URL: enter a provisional value, any value will do, the next step will overwrite this value. E.g., https://clinspark.com/
Be sure to leave the additional options unchecked (regarding spam check, and posting of raw, full MIME message).
Click ‘Add’
...