Domains

Before you can send emails through Kraiter, you need to verify a sending domain. Domain verification proves that you own the domain and authorises Kraiter (via AWS SES) to send emails on your behalf. Proper domain configuration also improves your email deliverability and protects your sender reputation.

Adding a domain

Register a new sending domain:

const domain = await kraiter.domains.create({
  domain: 'mail.example.com',
});

curl -X POST https://api.kraiter.com/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.example.com" }'

After creating the domain, Kraiter returns the DNS records you need to add to your domain's DNS configuration.

DNS records

You will need to add three types of DNS records to verify your domain and ensure proper email authentication.

DKIM (DomainKeys Identified Mail)

DKIM adds a cryptographic signature to your outgoing emails, allowing receiving mail servers to verify the message was not tampered with in transit.

Kraiter provides three CNAME records for DKIM. Add all three to your DNS:

Type: CNAME
Name: abcdef._domainkey.mail.example.com
Value: abcdef.dkim.amazonses.com

Type: CNAME
Name: ghijkl._domainkey.mail.example.com
Value: ghijkl.dkim.amazonses.com

Type: CNAME
Name: mnopqr._domainkey.mail.example.com
Value: mnopqr.dkim.amazonses.com

The exact record names and values are provided when you create the domain. These are unique to your domain.

SPF (Sender Policy Framework)

SPF tells receiving mail servers which servers are authorised to send email for your domain. If you are using a subdomain for sending (e.g. mail.example.com), add an MX record:

Type: MX
Name: mail.example.com
Value: 10 feedback-smtp.eu-west-1.amazonses.com

The region in the MX value depends on your AWS SES region.

DMARC (Domain-based Message Authentication)

DMARC ties together DKIM and SPF, telling receiving servers what to do when authentication fails. Add a TXT record to your domain:

Type: TXT
Name: _dmarc.example.com
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com

DMARC policies:

Start with p=none to monitor, then move to p=quarantine or p=reject once you are confident your configuration is correct.

Verification process

After adding the DNS records, Kraiter periodically checks your domain's DNS to verify the records are in place. This process typically takes a few minutes but can take up to 72 hours depending on DNS propagation.

Check the verification status:

const domain = await kraiter.domains.get('mail.example.com');
console.log(domain.status); // 'pending', 'verified', or 'failed'

curl https://api.kraiter.com/domains/mail.example.com \
  -H "Authorization: Bearer YOUR_API_KEY"

You can also trigger a manual verification check:

await kraiter.domains.verify('mail.example.com');

Domain status

Health monitoring

Once verified, Kraiter continuously monitors your domain's health. The health status reflects your sending reputation and delivery performance:

const domain = await kraiter.domains.get('mail.example.com');
console.log(domain.health); // 'healthy', 'warning', or 'critical'

• healthy — Bounce and complaint rates are within acceptable thresholds
• warning — Rates are approaching thresholds; investigate and address issues
• critical — Rates exceed thresholds; sending may be throttled or suspended

High bounce rates often indicate stale contact lists. High complaint rates suggest recipients are marking your emails as spam. See the Delivery guide for strategies to maintain good domain health.

Enabling and disabling sending

You can disable sending for a domain without deleting it. This is useful for temporarily pausing sends while you investigate delivery issues:

await kraiter.domains.disable('mail.example.com');

Re-enable when ready:

await kraiter.domains.enable('mail.example.com');

When a domain is disabled, any emails scheduled to send from that domain will be held until it is re-enabled.

Listing domains

List all domains in your tenant:

const { items } = await kraiter.domains.list();

curl https://api.kraiter.com/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a domain

Remove a domain from your tenant. This does not remove the DNS records from your DNS provider — you should clean those up manually.

await kraiter.domains.delete('mail.example.com');

curl -X DELETE https://api.kraiter.com/domains/mail.example.com \
  -H "Authorization: Bearer YOUR_API_KEY"

You cannot delete a domain that is actively being used by sequences or scheduled sends. Pause or archive any active sequences using the domain first.

Best practices

• Use a subdomain for sending. Send from mail.example.com or notifications.example.com rather than your root domain. This protects your root domain's reputation.
• Set up DMARC early. Even with a p=none policy, DMARC reporting helps you spot authentication issues.
• Monitor domain health. Regularly check your bounce and complaint rates. Act quickly if you see a warning or critical status.
• Do not share sending domains. Each application or service should have its own sending subdomain to isolate reputation.