API Documentation
Transactional
API Keys
Add a Domain
Copy
curl --request POST \
--url https://api.thepurplebox.io/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>' \
--data '
{
"value": "<string>"
}
'Copy
{
"status": 201,
"message": "domain added successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "v=spf1 xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
Domains
Add a Domain
Manage your domains for sending emails.
POST
https://api.thepurplebox.io
/
v1
/
domains
Add a Domain
Copy
curl --request POST \
--url https://api.thepurplebox.io/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>' \
--data '
{
"value": "<string>"
}
'Copy
{
"status": 201,
"message": "domain added successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "v=spf1 xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
Headers
application/jsonBody
The domain name to add.
Response
HTTP status code. Returns
201 when the domain identity is created successfully.A human-readable message describing the result of the operation.
Contains the domain identity configuration and DNS records required for verification.
Show properties
Show properties
Unique identifier for the domain identity.
The domain name that was added.
The team ID that owns this domain identity.
Current status of the domain. Possible values:
not_started, pending, success, failed, temporary_failure.Type of identity. Always
domain for domain identities.ISO 8601 timestamp when the domain identity was created.
ISO 8601 timestamp when the domain was verified. Null if not yet verified.
DNS configuration attributes required for domain verification.
Show properties
Show properties
DKIM (DomainKeys Identified Mail) record configuration for email authentication.
Show properties
Show properties
The DNS record name for the DKIM selector (e.g.,
thepurplebox._domainkey.yourdomain).The DNS record type. Always
TXT for DKIM records.The DKIM public key value to add to your DNS records. Starts with
v=DKIM1; k=rsa; p=.Time to Live for the DNS record. Can be
auto or a specific value in seconds.Verification status of the DKIM record. Possible values:
not_started, pending, success, failed.Array of DNS records required for configuring the MAIL FROM domain.
Show properties
Show properties
The subdomain name for the mail record (e.g.,
send.yourdomain or bounce.yourdomain).The DNS record type. Can be
TXT or CNAME.The DNS record value. For TXT records, contains SPF policy. For CNAME records, points to the bounce handler.
Time to Live for the DNS record in seconds (e.g.,
60).Verification status of the record. Possible values:
not_started, pending, success, failed.DMARC (Domain-based Message Authentication, Reporting, and Conformance) record configuration.
Show properties
Show properties
The DNS record name for DMARC. Always
_dmarc.The DNS record type. Always
TXT for DMARC records.The DMARC policy value (e.g.,
v=DMARC1;p=none;).Time to Live for the DNS record. Can be
auto or a specific value in seconds.Verification status of the DMARC record.
Overall verification status of the domain. Possible values:
not_started, pending, success, failed, temporary_failure.Indicates whether the domain is verified and ready to send emails. Returns
true when all DNS records are verified.Error type if verification fails. Empty string when no errors are present.
ISO 8601 timestamp of the last verification status check.
Copy
{
"status": 201,
"message": "domain added successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "v=spf1 xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
⌘I