POSTJECTDOCS

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 four TXT records: domain ownership verification, DKIM signing key, SPF policy, and DMARC policy. 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": "a3f9c2d4e8b1f6a5c7d2e4f8b3a1c6d9"
    },
    "dkim": {
      "type": "TXT",
      "name": "postject._domainkey.yourdomain.com",
      "value": "v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkq..."
    },
    "spf": {
      "type": "TXT",
      "name": "yourdomain.com",
      "value": "v=spf1 ip4:178.104.173.124 ~all"
    },
    "dmarc": {
      "type": "TXT",
      "name": "_dmarc.yourdomain.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@postject.com; pct=100"
    }
  },
  "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 four 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 (TXT Record)

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. A single TXT record containing the RSA public key is added at the postject._domainkey subdomain.

3. SPF Policy (TXT Record)

Sender Policy Framework (SPF) declares which mail servers are authorised to send email on behalf of your domain. Postject adds your domain's sending IP to the SPF record so receiving servers know the mail is legitimate.

4. DMARC Policy (TXT Record)

Domain-based Message Authentication, Reporting, and Conformance (DMARC) ties SPF and DKIM together and tells receiving servers what to do with mail that fails authentication checks. Postject sets a p=quarantine policy and forwards aggregate reports to dmarc@postject.com.

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

text
TYPE   NAME                                     VALUE
─────  ───────────────────────────────────────  ──────────────────────────────────────────────────────────────
TXT    _postject.yourdomain.com                 a3f9c2d4e8b1f6a5c7d2e4f8b3a1c6d9
TXT    postject._domainkey.yourdomain.com       v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkq...
TXT    yourdomain.com                           v=spf1 ip4:178.104.173.124 ~all
TXT    _dmarc.yourdomain.com                    v=DMARC1; p=quarantine; rua=mailto:dmarc@postject.com; pct=100

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"
}