Connect SendGrid to DNSconfig

What this gets you

When you authenticate a domain in SendGrid, SendGrid demands a handful of CNAME records be published in that domain's DNS. Normally you copy them into a ticket and hope the customer publishes them correctly — and that nobody deletes one a year later.

Connecting SendGrid to DNSconfig replaces that. The required records are read straight from your SendGrid account, so they are always exactly what SendGrid is asking for today. Whether the customer actually published them becomes something you can see rather than something you find out about.

You never paste record values by hand, and you never have to notice that SendGrid changed them — the next pull does.

Create the API key

In SendGrid: Settings → API Keys → Create API Key, and choose Restricted Access.

Grant Read access to:

Permission	Why
Sender Authentication	The domain-authentication records themselves. Required.
Subuser Management	Only if you are on a plan with subusers and use one per customer. Skip it otherwise.

Leave everything else off. Full Access works, but grants far more than this needs — DNSconfig only ever issues GET requests to SendGrid and never sends mail, changes settings, or touches your contacts.

Copy the key now. SendGrid shows it once. If you lose it, delete it in SendGrid and create another — there is no way to read it back.

Check it works before going further

Thirty seconds here saves diagnosing an empty pull later. With your key in $SG_KEY:

curl -s -H "Authorization: Bearer $SG_KEY" \
  https://api.sendgrid.com/v3/whitelabel/domains

You get	Means
A JSON array	Good. Empty `[]` just means no domain is authenticated yet — that's step 2.
`401`	The key is wrong or was truncated when copied.
`403`	The key lacks Sender Authentication read. Edit it in SendGrid.

Authenticate the customer's domain

In SendGrid: Settings → Sender Authentication → Authenticate Your Domain. Pick the customer's DNS host (choose Other if you're not sure — it changes nothing about the records produced), enter the domain, and continue.

SendGrid then shows the CNAMEs it requires — typically an em#### host plus s1._domainkey and s2._domainkey.

Don't copy them anywhere. That's the step this integration removes. Leave the records unpublished for now: DNSconfig is about to pull them, and the customer will publish them from their own page.

Repeat for each customer domain. One SendGrid connection covers all of them — you do not add a connection per domain.

Connect it in DNSconfig

Open Connections, add a SendGrid connection, paste the API key, and save.

Your key is encrypted before it is stored and is never returned by any read — the connection list only ever shows whether a credential is configured, never the value.

Managing connections requires a console session, or an API key carrying the secrets scope. See the developer documentation.

Pull the records

Press Sync now on the connection. You'll get back a count of what changed:

{ "source": "sendgrid",
  "added": 3, "updated": 0, "retired": 0, "unchanged": 0 }

Those three records are now expected state. They appear under a customer named after the domain, created for you if it didn't already exist — you don't have to set the customer up first.

added: 0 almost always means the domain isn't authenticated in SendGrid yet, or the key can't read Sender Authentication. Re-run the check from step 1.

What happens from then on

Every hour, the connection is re-pulled. Records SendGrid adds show up as new expected state; records it stops requiring are retired. Anything you entered by hand is never touched.
Four times an hour, every record is checked against live DNS from several independent resolvers. A record counts as correct only when a majority of the resolvers that answered agree, so a record published minutes ago reads as propagating rather than failing.
When a record's status changes, you're alerted — email, Slack, or your own webhook. Only transitions alert, so a record that has been broken for a week doesn't page you every fifteen minutes.
The customer fixes it themselves. Generate a link from the customer's page and send it. They open it with no account, copy the records with one click, publish them, and press Re-check.

Connection options

The defaults suit most accounts. Set these in the connection's config only if you need them.

Option	Effect
`single_account`	Skip the subuser lookup and pull the account's own domains. Rarely needed — the puller already falls back to this when an account has no subusers or the key can't read them.
`subusers`	A list of subuser usernames to pull, instead of all of them.
`include_disabled`	Also pull domains belonging to disabled subusers. Off by default.
`only_valid`	Pull only the CNAMEs SendGrid already considers valid. Off by default, and usually should stay off: a not-yet-valid domain is precisely the case worth monitoring.

Subusers are a paid SendGrid feature. If your account has none, the connection reads the account's own authenticated domains automatically — there is nothing to configure.

Troubleshooting

Symptom	Cause
Sync reports `added: 0`	No domain authenticated in SendGrid, or the key can't read Sender Authentication.
Sync fails, vendor unreachable	The key was revoked or mistyped. Re-run the step 1 check.
Records pulled, but all failing	Expected — until the customer publishes them. Send them their link.
A record stays propagating	Still spreading between resolvers, or published at one provider and not another. Normal within the first minutes of a change.
Records appeared under an unexpected customer	A customer already owned that domain, so the pull routed to it rather than creating a second one. Working as intended.

Still stuck? Mail hello@dns-config.net with the domain and what the sync reported.

Also using Mailgun? Connect Mailgun.

← Developer documentation