Domains & Identities

Verify your sending domains and email addresses to authenticate your emails and improve deliverability.

Identity Types

Postject supports two types of sender identities. Choose the type that fits your use case:

AUTHORITY (Domain)

Verifies an entire domain (e.g., yourdomain.com), allowing you to send from any address on that domain. Verification requires adding DNS records (TXT for domain ownership, CNAME for DKIM signing, and CNAME for bounce handling). This is the recommended approach for production use.

PERSONA (Email Address)

Verifies a single email address (e.g., hello@yourdomain.com). Verification is done via a confirmation link sent to that address. This is useful for quick testing or when you do not have access to DNS settings for the domain.

Add a Domain

Registers a new domain identity for verification. The response includes the DNS records you need to add to your domain's DNS configuration. Requires JWT Bearer authentication.

POSThttps://api.postject.com/v1/domains

Request Body

identifierstring (required)

The domain name to verify (e.g., "yourdomain.com").

typestring (required)

The identity type. Either AUTHORITY for a full domain or PERSONA for a single email address.

json

{
  "identifier": "yourdomain.com",
  "type": "AUTHORITY"
}

Response

json

{
  "id": "clx9e7q5f0009az2z4r5s6t7u",
  "identifier": "yourdomain.com",
  "type": "AUTHORITY",
  "verified": false,
  "dnsRecords": {
    "verification": {
      "type": "TXT",
      "name": "_postject.yourdomain.com",
      "value": "postject-verify=clx9e7q5f0009az2z4r5s6t7u"
    },
    "dkim": [
      {
        "type": "CNAME",
        "name": "pj1._domainkey.yourdomain.com",
        "value": "pj1.dkim.postject.com"
      },
      {
        "type": "CNAME",
        "name": "pj2._domainkey.yourdomain.com",
        "value": "pj2.dkim.postject.com"
      },
      {
        "type": "CNAME",
        "name": "pj3._domainkey.yourdomain.com",
        "value": "pj3.dkim.postject.com"
      }
    ],
    "returnPath": {
      "type": "CNAME",
      "name": "pm-bounces.yourdomain.com",
      "value": "pm.mtasv.net"
    }
  },
  "createdAt": "2025-07-16T14:00:00.000Z"
}

DNS Configuration

After adding a domain identity, you need to configure the following DNS records with your DNS provider. All five records are required for full verification and optimal deliverability.

1. Domain Verification (TXT Record)

Proves ownership of the domain. Add a TXT record at the specified subdomain with the verification token provided in the API response.

2. DKIM Signing (3 CNAME Records)

DomainKeys Identified Mail (DKIM) adds a cryptographic signature to your emails, allowing receiving servers to verify that the email was authorized by the domain owner and was not modified in transit. Three CNAME records are required.

3. Return Path (1 CNAME Record)

Configures bounce handling so that bounced emails are routed back to Postject for processing. This allows Postject to automatically update message statuses and manage your suppression list.

Here is the full set of DNS records you need to add for a domain:

text

TYPE    NAME                                VALUE
─────   ──────────────────────────────────  ─────────────────────────────────────────────
TXT     _postject.yourdomain.com            postject-verify=clx9e7q5f0009az2z4r5s6t7u
CNAME   pj1._domainkey.yourdomain.com       pj1.dkim.postject.com
CNAME   pj2._domainkey.yourdomain.com       pj2.dkim.postject.com
CNAME   pj3._domainkey.yourdomain.com       pj3.dkim.postject.com
CNAME   pm-bounces.yourdomain.com           pm.mtasv.net

DNS Propagation

DNS changes can take up to 48 hours to propagate, although most providers update within minutes. You can check the verification status at any time using the verify endpoint.

Add an Email Identity

To verify a single email address instead of a full domain, use the same endpoint with the type set to PERSONA. A confirmation email will be sent to the specified address with a verification link.

POSThttps://api.postject.com/v1/domains

json

{
  "identifier": "hello@yourdomain.com",
  "type": "PERSONA"
}

Response

json

{
  "id": "clx9f8r6g0010bz3z5s6t7u8v",
  "identifier": "hello@yourdomain.com",
  "type": "PERSONA",
  "verified": false,
  "dnsRecords": null,
  "createdAt": "2025-07-16T14:30:00.000Z"
}

Check the inbox of the specified email address for a confirmation email from Postject. Click the verification link to complete the process.

Check Verification Status

Triggers a verification check for a domain identity. For AUTHORITY identities, Postject queries the DNS records to confirm they are correctly configured. For PERSONA identities, it checks whether the confirmation link has been clicked. Requires JWT Bearer authentication.

GEThttps://api.postject.com/v1/domains/:id/verify

json

{
  "id": "clx9e7q5f0009az2z4r5s6t7u",
  "identifier": "yourdomain.com",
  "type": "AUTHORITY",
  "verified": true,
  "dnsRecords": {
    "verification": {
      "type": "TXT",
      "name": "_postject.yourdomain.com",
      "value": "postject-verify=clx9e7q5f0009az2z4r5s6t7u",
      "status": "verified"
    },
    "dkim": [
      {
        "type": "CNAME",
        "name": "pj1._domainkey.yourdomain.com",
        "value": "pj1.dkim.postject.com",
        "status": "verified"
      },
      {
        "type": "CNAME",
        "name": "pj2._domainkey.yourdomain.com",
        "value": "pj2.dkim.postject.com",
        "status": "verified"
      },
      {
        "type": "CNAME",
        "name": "pj3._domainkey.yourdomain.com",
        "value": "pj3.dkim.postject.com",
        "status": "verified"
      }
    ],
    "returnPath": {
      "type": "CNAME",
      "name": "pm-bounces.yourdomain.com",
      "value": "pm.mtasv.net",
      "status": "verified"
    }
  },
  "createdAt": "2025-07-16T14:00:00.000Z"
}

List All Identities

Returns all domain and email identities for the authenticated user's account. Requires JWT Bearer authentication.

GEThttps://api.postject.com/v1/domains

json

[
  {
    "id": "clx9e7q5f0009az2z4r5s6t7u",
    "identifier": "yourdomain.com",
    "type": "AUTHORITY",
    "verified": true,
    "createdAt": "2025-07-16T14:00:00.000Z"
  },
  {
    "id": "clx9f8r6g0010bz3z5s6t7u8v",
    "identifier": "hello@yourdomain.com",
    "type": "PERSONA",
    "verified": true,
    "createdAt": "2025-07-16T14:30:00.000Z"
  },
  {
    "id": "clx9g9s7h0011cz4z6t7u8v9w",
    "identifier": "staging.yourdomain.com",
    "type": "AUTHORITY",
    "verified": false,
    "createdAt": "2025-07-17T09:00:00.000Z"
  }
]

Remove an Identity

Permanently removes a domain or email identity from your account. After removal, you will no longer be able to send emails from this domain or address. Requires JWT Bearer authentication.

DELETEhttps://api.postject.com/v1/domains/:id

Note

Removing an identity does not delete the DNS records from your domain provider. You should manually remove the Postject DNS records after deleting the identity to keep your DNS configuration clean.

json

{
  "message": "Identity deleted successfully",
  "id": "clx9e7q5f0009az2z4r5s6t7u"
}