Start verification for a domain you already own so Pingram can use it for email. Pass a bare domain (example.com) or subdomain (mail.example.com). This does not purchase, transfer, renew, or control the domain, does not edit DNS, and does not disable sending or receiving on other platforms. It saves the domain on this Pingram account and returns DNS records for you to publish. Required DKIM lets Pingram send email from addresses on this domain once verification completes. Optional inbound MX, once you publish it, routes that domain's inbound email to Pingram. This call only begins verification. Publish the records, then start verification in the dashboard or with the start-verification API. Adding a domain that is already on the account returns the existing records.

POST

/domains

curl --request POST \
  --url https://api.pingram.io/domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sender": "example" }'

• Production

Authorizations

• apiKey
• clientCredentials
• endUser
• endUserHashed

Request Body^required

Media typeapplication/json

object

sender

required

string

Example^generated

{
  "sender": "example"
}

Responses

200

Successful response

Media typeapplication/json

Array<object>

object

sender

required

string

status

required

string

Allowed values: SUCCESS PENDING FAILED TEMPORARY_FAILURE NOT_STARTED

lastSync

required

string format: date-time

verificationTokens

Array<string>

mailFromDomainStatus

string

Allowed values: PENDING SUCCESS FAILED TEMPORARY_FAILURE

createdAt

required

string

privateDKIMKey

string

reminderSentAt

string

selector

required

string

verificationRecords

Keyed by record id — computed on domain API responses, not stored in DB.

object

dkim

DNS record the customer must publish for domain verification.

object

recordType

required

string

Allowed values: TXT MX

recordName

required

Relative name for the parent DNS zone UI (e.g. pingram._domainkey.testing).

string

host

required

Full hostname (e.g. pingram._domainkey.testing.something.com).

string

recordValue

required

string

priority

number

required

boolean

mail_from_spf

DNS record the customer must publish for domain verification.

object

recordType

required

string

Allowed values: TXT MX

recordName

required

Relative name for the parent DNS zone UI (e.g. pingram._domainkey.testing).

string

host

required

Full hostname (e.g. pingram._domainkey.testing.something.com).

string

recordValue

required

string

priority

number

required

boolean

mail_from_mx

DNS record the customer must publish for domain verification.

object

recordType

required

string

Allowed values: TXT MX

recordName

required

Relative name for the parent DNS zone UI (e.g. pingram._domainkey.testing).

string

host

required

Full hostname (e.g. pingram._domainkey.testing.something.com).

string

recordValue

required

string

priority

number

required

boolean

dmarc

DNS record the customer must publish for domain verification.

object

recordType

required

string

Allowed values: TXT MX

recordName

required

Relative name for the parent DNS zone UI (e.g. pingram._domainkey.testing).

string

host

required

Full hostname (e.g. pingram._domainkey.testing.something.com).

string

recordValue

required

string

priority

number

required

boolean

inbound_mx

DNS record the customer must publish for domain verification.

object

recordType

required

string

Allowed values: TXT MX

recordName

required

Relative name for the parent DNS zone UI (e.g. pingram._domainkey.testing).

string

host

required

Full hostname (e.g. pingram._domainkey.testing.something.com).

string

recordValue

required

string

priority

number

required

boolean

Example

[
  {
    "status": "SUCCESS",
    "mailFromDomainStatus": "PENDING",
    "verificationRecords": {
      "dkim": {
        "recordType": "TXT"
      },
      "mail_from_spf": {
        "recordType": "TXT"
      },
      "mail_from_mx": {
        "recordType": "TXT"
      },
      "dmarc": {
        "recordType": "TXT"
      },
      "inbound_mx": {
        "recordType": "TXT"
      }
    }
  }
]

400

Bad Request - validation errors, invalid input

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

401

Unauthorized

402

Payment Required - usage limits exceeded

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

500

Internal Server Error

502

Bad Gateway - provider error

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}