Summary

This article focuses on the required configuration of SendGrid to work with ClinSpark.

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.

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 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:

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 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 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 simlar to this:

In the above example, the different parts of the domain name have the following mapping:

• fhvalmail –> cs-mailer-subdomain

• clinspark (.com) –> org-domain (.com)

The domain that needs to be validated in this example is cs-mailer-subdomain.org-domain.com. In addition to the MX record, a TXT record for SPF (spamfilter - related record) needs to be added as well.

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.

Please refer to SendGrid’s documentation for this step.

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 ).

Usually you’ll need to add the following records for the main domain:

• 3600 MX 10 mx.sendgrid.net.

• 3600 TXT “v=spf1 include:sendgrid.net ~all”

(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:

Step 1 Within sendgrid, navigate to Settings > Inbound Parse.

Step 2 Press ‘Add Host & URL’ button

Step 3 Provide the following details:

• 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’

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.

See also

1. Manage Correspondence