Skip to main content

​
Domains

Before you can send email, you need at least one verified domain. Numonic registers your domain with AWS SES and provides the DNS records you need to prove ownership and enable DKIM signing. All domain endpoints require JWT authentication.

​
Register a domain

POST /api/v1/domains
Registers a domain and returns the DNS records you need to add.

​
Request

curl -X POST https://api.numonic.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_name": "yourapp.com"
  }'

​
Body parameters

ParameterTypeRequiredDescription
domain_namestringYesThe domain to register (e.g. yourapp.com)

​
Response 201

{
  "tenant_id":   "550e8400-e29b-41d4-a716-446655440000",
  "domain_id":   123,
  "domain_name": "yourapp.com",
  "identity_arn": "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
  "dns_records": [
    {
      "type":  "TXT",
      "name":  "_amazonses.yourapp.com",
      "value": "abc123def456..."
    },
    {
      "type":  "CNAME",
      "name":  "abc123._domainkey.yourapp.com",
      "value": "abc123.dkim.amazonses.com"
    }
  ]
}
Add all returned DNS records at your domain registrar. Verification typically completes within minutes but can take up to 72 hours.

​
Errors

StatusCodeCause
409CONFLICTDomain is already registered
422VALIDATION_ERRORInvalid domain format

​
List domains

GET /api/v1/domains
Returns all domains registered to your account.

​
Request

curl https://api.numonic.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT"

​
Response 200

[
  {
    "domain_id":              123,
    "tenant_id":              "550e8400-e29b-41d4-a716-446655440000",
    "domain_name":            "yourapp.com",
    "verification_status":    "Success",
    "identity_arn":           "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
    "configuration_set_name": "numonic-emails"
  }
]

​
Verification status values

StatusMeaning
PendingDNS records not yet detected
SuccessDomain verified and ready to send
FailedDNS records incorrect or not found

​
Get domain details

GET /api/v1/domains/:id
Returns full details for a single domain, including DNS records.

​
Request

curl https://api.numonic.com/api/v1/domains/123 \
  -H "Authorization: Bearer YOUR_JWT"

​
Response 200

{
  "domain_id":              123,
  "tenant_id":              "550e8400-e29b-41d4-a716-446655440000",
  "domain_name":            "yourapp.com",
  "verification_status":    "Success",
  "identity_arn":           "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
  "configuration_set_name": "numonic-emails",
  "dns_records": [
    {
      "type":  "TXT",
      "name":  "_amazonses.yourapp.com",
      "value": "abc123def456..."
    },
    {
      "type":  "CNAME",
      "name":  "abc123._domainkey.yourapp.com",
      "value": "abc123.dkim.amazonses.com"
    }
  ]
}

​
Errors

StatusCodeCause
404NOT_FOUNDDomain not found or belongs to another tenant

​
Delete a domain

DELETE /api/v1/domains/:id
Removes a domain from your account and deregisters it from SES.

​
Request

curl -X DELETE https://api.numonic.com/api/v1/domains/123 \
  -H "Authorization: Bearer YOUR_JWT"

​
Response 200

{
  "success": true
}

​
Errors

StatusCodeCause
404NOT_FOUNDDomain not found or belongs to another tenant