Domains API

Endpoints

With a project key — no project id, because the key already says which one:

With an all-access key, naming the project:

Same bodies, same responses. Add the domain a project sends from and publish the DNS records that come back. Until one is verified, sends use the shared testing domain — see Sending domains for why that matters.

List a project's domains

# project key
curl https://emailbump.com/api/v1/domains \
  -H "Authorization: Bearer ebk_your_key"

# all-access key
curl https://emailbump.com/api/v1/projects/PROJECT_ID/domains \
  -H "Authorization: Bearer ebk_all_access_key"

Returns every sending domain on the project with its verification state and the DNS records it needs. Check this before setting a From address: mail from a domain that isn’t verified doesn’t land anywhere good.

Add a domain

# project key
curl -X POST https://emailbump.com/api/v1/domains \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.acme.com" }'

# all-access key
curl -X POST https://emailbump.com/api/v1/projects/7a10…/domains \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.acme.com" }'

The response carries the DKIM and mail-from records to publish at your DNS provider, exactly as they should be entered.

Branded link tracking

Until you turn this on, links in your mail are rewritten through Email Bump's shared tracking domain. That works — clicks are recorded and nothing breaks — but someone hovering a link sees our domain rather than yours.

curl -X POST https://emailbump.com/api/v1/domains/DOMAIN_ID/tracking \
  -H "Authorization: Bearer ebk_your_key"

DELETE on the same path turns it off and returns you to the shared domain.

Re-enabling with POST reuses any retained certificate and CDN distribution. If both exist and the certificate is issued, tracking_status can move straight to deploying. Keep the existing DNS records published; no new records are needed when they still match. If the certificate is pending, provisioning was incomplete, or a provider check fails, keep polling and follow the returned status and DNS records.

Check verification

Poll the domain until it reports verified. DNS usually propagates in minutes, though some providers take up to 48 hours.

curl https://emailbump.com/api/v1/projects/7a10…/domains/DOMAIN_ID \
  -H "Authorization: Bearer ebk_all_access_key"

There is no public /v1 POST /verify endpoint. This GET re-polls the provider; background checks also run. Use the returned verification state, not elapsed time, to decide when it is ready.

See which record is missing

Verification is one bit: verified or not. When it stays pending, dns-check resolves each record and says which one is the reason.

curl https://emailbump.com/api/v1/domains/DOMAIN_ID/dns-check \
  -H "Authorization: Bearer ebk_your_key"

{
  "records": [ ... ],
  "missing": [
    {
      "type": "CNAME",
      "host": "hrgx55svace3aeq43mxk3hmjhtrcjlic._domainkey.acme.com",
      "value": "hrgx55svace3aeq43mxk3hmjhtrcjlic.dkim.amazonses.com",
      "purpose": "DKIM",
      "state": "missing"
    }
  ],
  "next": "Publish the 1 record in `missing` at your DNS provider, then check again. DNS usually propagates within minutes but can take up to 72 hours.",
  "all_found": false,
  "lookups_failed": false
}

missing is the work that is left, already filtered: the records you still have to publish, in full, so a client can print the fix without walking records itself. A record whose lookup failed never appears in it — unknown is not work. next is that same answer as one line of English, safe to show a person as-is.

Every record in records comes back with a state:

all_found covers the required records only. The optional branded-tracking CNAMEs arrive one at a time, so counting them would keep it false for every domain part-way through tracking setup. They can still show up in missing — they really are unpublished — carrying optional: true, and next names them separately so nobody reads a pending tracking record as a failed verification.

DKIM key length

Sets the domain’s DKIM key length to 1024 or 2048 bits. Changing it is what makes the provider generate new key material.

curl -X POST https://emailbump.com/api/v1/domains/DOMAIN_ID/dkim/key-length \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"bits": 2048}'

Unsupported lengths, requests for the current or already-requested length, and provider-refused changes return 400 with a reason. The provider restricts how frequently key length can change; inspect that reason before retrying.

Remove a domain

Deletes the domain and the sending identity behind it. Mail stops going out as that brand immediately and the records the customer published go dead. There is no undo.

curl -X DELETE https://emailbump.com/api/v1/domains/DOMAIN_ID \
  -H "Authorization: Bearer ebk_your_key"