Configuration

Configuration is the one-time work that turns an installed package into a governed sending platform: authenticate a domain, connect a provider, and set org defaults.

Pre-Installation Checklist

Before you begin, confirm these items are in place. Skipping a step usually shows up later as a generic "Failed to send an email" message.

• SendGrid API Key created
• Named Credential configured
• Domain Authentication completed, or all sending users verified as Single Senders
• Send Test Email successful

1. Authenticate your sending domain

Create a Sending_Domain__c record for each domain, then publish the DNS records exactly as your provider generates them.

SendGrid Automated Domain Authentication does not ask you to add a generic include:sendgrid.net value to your root SPF record. It establishes SPF alignment through an account-specific return-path CNAME, for example:

em9963.example.com.  CNAME  u112773715.wl123.sendgrid.net.

The hostname and target are generated per SendGrid account. Copy every DNS name and target directly from the SendGrid domain-authentication screen — never guess or reuse values from another account or from documentation.

DKIM and DMARC follow the same rule. The records below are examples only; your selectors and targets will differ.

; DKIM — SendGrid supplies two selectors, both account specific
s1._domainkey.example.com.  CNAME  s1.domainkey.u112773715.wl123.sendgrid.net.
s2._domainkey.example.com.  CNAME  s2.domainkey.u112773715.wl123.sendgrid.net.

; DMARC — start at none, move to quarantine, then reject
_dmarc.example.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com; fo=1"

Click Verify Domain. RME resolves the records and sets Status__c = Verified. Sends from an unverified domain are blocked by default.

2. SendGrid DNS Configuration with Cloudflare

SendGrid domain authentication typically generates three account-specific CNAME records. All three must resolve publicly and must not be proxied.

Operational guidance:

• Copy every hostname and target directly from SendGrid.
• Set all email-authentication CNAME records to DNS only in Cloudflare.
• The Cloudflare cloud must be gray, not orange.
• Never proxy em####, s1._domainkey, or s2._domainkey.
• Cloudflare proxying can prevent receiving mail systems from resolving the authentication records.
• SendGrid may continue showing an old configuration as "Verified" even if a record was subsequently deleted or proxied.
• Always validate using a newly sent email and the receiving provider's authentication results.

3. SendGrid Link Branding and Click Tracking

When click tracking is enabled, SendGrid rewrites every tracked URL so it passes through a branded hostname on your domain, for example url559.integrationready.com. If that hostname does not resolve, every link in the email breaks — even though the destination page itself is healthy.

Link Branding commonly provides two CNAME records:

Example — the Integration Ready implementation:

Setup sequence:

1. Create both Link Branding CNAME records in Cloudflare.
2. Keep both records DNS only during initial SendGrid verification.
3. Return to SendGrid and click Verify.
4. Confirm the Link Branding configuration reports Verified.
5. Test the branded hostname in a browser before sending a production campaign.

4. HTTPS/TLS for Branded Tracking Links

Three separate controls are often confused with one another:

Successful TLS delivery of the email does not automatically provide HTTPS for the branded click-tracking hostname. That hostname needs its own certificate coverage. Two approaches are supported.

Option A — SendGrid automatic certificate provisioning

The SendGrid Link Branding workflow may offer one of these settings, depending on account and UI version:

• Auto provision SSL Certificate
• Use Transport Layer Security
• Automated Security

When enabled, SendGrid may provide additional DNS validation records. Add every record exactly as SendGrid provides it and allow time for certificate issuance before testing.

Reference: How to set up link branding — Twilio SendGrid↗

Option B — Cloudflare Universal SSL

This is the configuration validated for Integration Ready:

1. Confirm Cloudflare Universal SSL is active for *.integrationready.com.
2. Create and verify the SendGrid Link Branding records while they are DNS only.
3. After SendGrid verification, change only the public tracking hostname, such as url559, to Proxied.
4. Leave the SendGrid account-number hostname DNS only.
5. Leave all email-authentication records DNS only.
6. Do not repeatedly reverify the Link Branding configuration after proxying the public hostname.

Final Integration Ready record settings:

If the public tracking record is DNS only and SendGrid has not provisioned a certificate, the hostname may resolve but produce a browser HTTPS certificate error. When proxied, Cloudflare can present its active wildcard certificate for the tracking hostname.

Do not change the SSL mode for the entire Cloudflare zone. If a hostname-specific SSL adjustment is required, use a narrowly scoped Cloudflare Configuration Rule, or let SendGrid manage TLS with Option A.

5. SendGrid Authentication and Link-Tracking Troubleshooting

6. Create the Named Credential

RME never stores provider API keys in custom fields. Credentials live in Named Credentials and External Credentials.

External Credential: RME_SendGrid
  Authentication Protocol : Custom
  Principal               : NamedPrincipal "SendGrid_API"
  Custom Header           : Authorization = Bearer {!$Credential.Password}

Named Credential: RME_SendGrid
  URL                     : https://api.sendgrid.com
  External Credential     : RME_SendGrid
  Allowed Namespaces      : rme
  Generate Auth Header    : Enabled

Grant the External Credential Principal to the RME_Administrator and RME_Integration_User permission sets.

7. Verify Sender Email Addresses (Required)

Option 1 (Recommended for Production): Authenticate Your Entire Email Domain

If your organization authenticates its domain (for example, integrationready.com), then all email addresses on that domain are automatically valid senders.

This is the recommended production configuration because it supports all users without requiring individual verification and provides the best email deliverability.

Option 2 (Quick Start / Testing): Verify Individual Senders

If Domain Authentication has not yet been configured:

1. Log into SendGrid.
2. Navigate to Settings → Sender Authentication → Single Sender Verification.
3. Click Verify a Single Sender.
4. Enter the required fields:
   • From Name
   • From Email Address
   • Reply-To
   • Company Address
   • City / State / Zip
5. Click Create.
6. Open the verification email sent to that address.
7. Click Verify Sender.

Repeat this process for every Salesforce user who will send email through Real Messenger Engine.

Common Symptoms

If a sender has not been verified, users may experience:

• "Failed to send an email."
• Generic Salesforce error message.
• SendGrid rejects the request because the sender identity is not verified.

Troubleshooting

Verify:

• The logged-in Salesforce user's email matches a verified SendGrid sender.
• OR the sender's domain has been authenticated.
• The SendGrid API Key is valid.
• The SendGrid Named Credential is configured correctly.

Best Practice

8. Register the provider

Create a Provider_Config__c record:

See Communication Providers for per-provider settings.

9. Set org defaults

In RME Settings:

defaultFromName:        "Real Intelligence"
defaultFromAddress:     "no-reply@example.com"
defaultReplyTo:         "support@example.com"
defaultDomain:          "example.com"
sandboxMode:            true      # rewrites all recipients to a test inbox
sandboxRedirectTo:      "qa@example.com"
retryPolicy:            "exponential:5:24h"
suppressionEnforcement: "strict"
consentEnforcement:     "strict"
eventRetentionDays:     730

10. Configure webhooks

Register the RME event endpoint with each provider so delivery events return to Salesforce. See Webhooks for endpoint URLs and signature verification.

11. Validate end to end

RME_Message.Result r = RME_Message.builder()
    .channel('EMAIL')
    .toAddress('qa@example.com')
    .subject('RME configuration test')
    .body('If you received this, delivery is configured.')
    .send();

System.assertEquals('SENT', r.status);

Confirm a Message__c record, a Delivery_Status__c of Delivered, and an inbound webhook event within a minute.

12. Final Deliverability Validation

• Send a completely new test email after making DNS changes.
• Confirm the From address uses the authenticated domain.
• In Gmail, open the message.
• Select the three-dot message menu.
• Select Show original.
• Confirm:

SPF: PASS
DKIM: PASS
DMARC: PASS

Also confirm:

• DKIM is signed with the visible From domain.
• The SendGrid return-path uses the intended authenticated em#### subdomain.
• The branded HTTPS tracking link resolves without an NXDOMAIN or certificate error.
• The tracking link redirects to the intended destination.
• Images use a trusted first-party HTTPS domain where practical.
• A plain-text MIME version accompanies the HTML email.
• Production marketing emails include the required unsubscribe mechanism and sender identification.

Integration Ready validated configuration

Continue to Communication Providers.

Last updated 1 month ago