Skip to main content
Before you can send emails, at least one domain must be added to your project and verified via DNS. All from addresses used in transactional emails, templates, and campaigns must belong to a verified domain.
Domain endpoints require user authentication and a verified email address. They are scoped to a specific project by projectId.

​
Get domains for a project

GET /domains/project/:projectId Returns all domains linked to a project.

​
Path parameters

​
projectId
string
required
The project ID.

​
Response

Array of domain objects.
​
id
string
Domain record ID.
​
domain
string
Domain name (e.g. myapp.com).
​
projectId
string
ID of the project this domain belongs to.
​
verified
boolean
Whether the domain has passed DNS verification.
​
createdAt
string
ISO 8601 timestamp when the domain was added.
Example
curl --request GET \
  --url https://next-api.useplunk.com/domains/project/clx_proj_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'
200
[
  {
    "id": "clx_dom_abc123",
    "domain": "myapp.com",
    "projectId": "clx_proj_abc123",
    "verified": true,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

​
Add domain

POST /domains Adds a new domain to a project. After adding, DNS records must be configured before the domain passes verification.
You must be an admin of the target project to add a domain. A domain can only be linked to one project at a time — attempting to add a domain that is already linked to another project will return an error.

​
Body parameters

​
projectId
string
required
The project to link the domain to.
​
domain
string
required
The domain name to add, e.g. myapp.com. Do not include a protocol or path.

​
Response

Returns the newly created domain object with HTTP 201.
​
id
string
Domain record ID.
​
domain
string
Domain name.
​
projectId
string
Linked project ID.
​
verified
boolean
false until DNS verification passes.
​
createdAt
string
ISO 8601 creation timestamp.
Example
curl --request POST \
  --url https://next-api.useplunk.com/domains \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "projectId": "clx_proj_abc123",
    "domain": "myapp.com"
  }'

​
Check domain verification

GET /domains/:id/verify Triggers a fresh DNS verification check for the domain and returns the updated verification status.
Poll this endpoint after configuring your DNS records to confirm when verification succeeds.

​
Path parameters

​
id
string
required
The domain record ID.

​
Response

Returns the verification status object.
​
verified
boolean
true when all required DNS records are correctly configured.
Example
curl --request GET \
  --url https://next-api.useplunk.com/domains/clx_dom_abc123/verify \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "verified": true
}

​
Remove domain

DELETE /domains/:id Removes a domain from its linked project.
Removing a verified domain will immediately prevent emails from being sent using any from address on that domain. Update all templates and campaigns that use the domain before removing it.
You must be an admin of the project the domain belongs to.

​
Path parameters

​
id
string
required
The domain record ID.

​
Response

​
success
boolean
true on successful removal.
Example
curl --request DELETE \
  --url https://next-api.useplunk.com/domains/clx_dom_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "success": true
}

Build docs developers (and LLMs) love

Get started for freeTalk to us