ReferenceAdmin Centre API

Domains

Email domains. A domain is added, then verified by publishing a DNS TXT record; only verified domains can be used for usernames and mailboxes. Bramble checks verified domains again later and marks them "verification lost" if the record disappears.

Method	Path	Summary
GET	`/v1/admin/tenant/domains`	List the tenant's verified/pending domains
POST	`/v1/admin/tenant/domains/verify`	Check a domain's verification record
POST	`/v1/admin/tenant/domains/add`	Add a domain
POST	`/v1/admin/domains/view`	Get a domain
DELETE	`/v1/admin/tenant/domains`	Remove a domain

#List the tenant's verified/pending domains

GET/v1/admin/tenant/domains

List the tenant's verified/pending domains. Requires the GLOBAL_ADMIN role.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Response 200

Field	Type	Description
`domains`	array of any

Example response

JSON

{
  "domains": []
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains' -Headers $headers

#Check a domain's verification record

POST/v1/admin/tenant/domains/verify

Re-check a domain's DNS TXT verification record. Requires the GLOBAL_ADMIN role. Compares live DNS TXT records against the stored verification string. Sets domain_status to 1 (verified) on match; if a previously-verified domain (status 1) no longer matches, flips it to 3 (verification lost). System domains (status 2) cannot be re-verified.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/verify
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Request body JSON

Name	Type	Description
`domain_id`required	integer

Response 200

Field	Type	Description
`success`	boolean
`domain`	string
`verified`	any
`checked_records`	array of any

Example response

JSON

{
  "success": true,
  "domain": "string",
  "verified": null,
  "checked_records": []
}

Errors

Status	Message
400	domain_id is required
400	No verification token set for this domain
400	System domains do not need verification
404	Domain not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/verify' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":7}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/verify', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"domain_id":7}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/verify",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"domain_id":7},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"domain_id":7}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/verify' -Headers $headers -ContentType 'application/json' -Body $body

#Add a domain

POST/v1/admin/tenant/domains/add

Returns the TXT record to publish in the domain's DNS to prove you own it.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/add
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Request body JSON

Name	Type	Description
`domain`	string	The domain, e.g. `example.com`.

Response 200

Field	Type	Description
`success`	boolean
`message`	string
`id`	integer
`domain`	string
`verifyRecord`	object
`verifyRecord.name`	string
`verifyRecord.type`	string
`verifyRecord.value`	any

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "id": 42,
  "domain": "string",
  "verifyRecord": {
    "name": "Example name",
    "type": "string",
    "value": null
  }
}

Errors

Status	Message
400	Domain invalid format!
404	User not found
403	This domain cannot be added
403	This domain contains a banned string
409	Domain already in use

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/add' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"string"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/add', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"domain":"string"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/add",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"domain":"string"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"domain":"string"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains/add' -Headers $headers -ContentType 'application/json' -Body $body

#Get a domain

POST/v1/admin/domains/view

Get a single tenant domain by id. Requires the GLOBAL_ADMIN role. POST (not GET) — used as a lookup-by-id action from the admin UI.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/domains/view
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Request body JSON

Name	Type	Description
`domain_id`	integer

Response 200

Field	Type	Description
`domain`	string

Example response

JSON

{
  "domain": "string"
}

Errors

Status	Message
404	User not found
404	No Data Found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/domains/view' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":7}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/domains/view', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"domain_id":7}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/domains/view",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"domain_id":7},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"domain_id":7}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/domains/view' -Headers $headers -ContentType 'application/json' -Body $body

#Remove a domain

DELETE/v1/admin/tenant/domains

Remove a tenant domain. Requires the GLOBAL_ADMIN role. System domains (domain_status=2) cannot be removed.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Request body JSON

Name	Type	Description
`domain_id`required	integer

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	domain_id is required
404	Domain not found
403	System domains cannot be removed

Example request

Bash

curl -X DELETE 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.delete(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method DELETE -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/domains' -Headers $headers

Was this page helpful?