Mail API · Dashboard
Custom domains & DNS
Claim ownership, review the $2 setup charge, provision a domain, and inspect individual DNS checks.
Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.
How to use these endpoints
- Claim the exact domain and publish the returned ownership TXT challenge.
- Verify the challenge; this proves control of the domain, not mail readiness.
- Preview and confirm the one-time $2 setup charge. The purchase is idempotent.
- Publish the returned MX, SPF, DKIM, and DMARC records and run separate DNS checks.
Claim a domain
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/mail/domains/claim" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain":"example.com"}'The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.
Endpoint reference
Dashboard endpoints (9)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/projects/:projectId/mail/domains/billing | Preview a custom-domain setup charge |
| POST | /api/v1/projects/:projectId/mail/domains/claim | Start a custom-domain ownership claim |
| GET | /api/v1/projects/:projectId/mail/domains | List project mail domains |
| POST | /api/v1/projects/:projectId/mail/domains/:domainId/add | Purchase and provision a verified domain |
| DELETE | /api/v1/projects/:projectId/mail/domains/:domainId/delete | Remove an owned custom domain |
| POST | /api/v1/projects/:projectId/mail/domains/:domainId/dns/verify | Check custom-domain DNS records |
| POST | /api/v1/projects/:projectId/mail/domains/:domainId/sending-plan/change | Change a domain's sending plan |
| GET | /api/v1/projects/:projectId/mail/domains/:domainId/sending-plan | Read a domain's sending plan |
| POST | /api/v1/projects/:projectId/mail/domains/:domainId/verify | Verify domain ownership |
GETPreview a custom-domain setup chargeDetails +/api/v1/projects/:projectId/mail/domains/billing
Returns the one-time USD 2.00 fee, available personal or organization balances, the balance source that would be charged, and the resulting balances.
- This is a preview only. It does not reserve the name, verify ownership or charge the account.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "type": "string" }, "feeMicroUsd": { "type": "string" }, "paidBalanceMicroUsd": { "type": "string" }, "promotionalBalanceMicroUsd": { "type": "string" }, "resultingPaidBalanceMicroUsd": { "type": "string" }, "resultingPromotionalBalanceMicroUsd": { "type": "string" }, "affordable": { "type": "boolean" } }, "required": [ "currency", "feeMicroUsd", "paidBalanceMicroUsd", "promotionalBalanceMicroUsd", "resultingPaidBalanceMicroUsd", "resultingPromotionalBalanceMicroUsd", "affordable" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "currency": "string", "feeMicroUsd": "string", "paidBalanceMicroUsd": "string", "promotionalBalanceMicroUsd": "string", "resultingPaidBalanceMicroUsd": "string", "resultingPromotionalBalanceMicroUsd": "string", "affordable": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTStart a custom-domain ownership claimDetails +/api/v1/projects/:projectId/mail/domains/claim
Reserves a domain claim for this project and returns a unique _hubfly-mail.<domain> TXT challenge. Publish the value exactly before verifying ownership.
- The domain is not active and no setup fee is charged until ownership is verified and the add operation is confirmed.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
domain | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"domain": {
"type": "string"
}
},
"required": [
"domain"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "state": { "type": "string" }, "record": { "type": "object", "properties": { "type": { "const": "TXT", "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "name", "value" ], "additionalProperties": false } }, "required": [ "id", "domain", "state", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "state": { "const": "ownership_pending", "type": "string" }, "record": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "name", "value" ], "additionalProperties": false } }, "required": [ "id", "domain", "state", "record" ], "additionalProperties": false } ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": null, "meta": { "requestId": "string", "timestamp": "string" } }
GETList project mail domainsDetails +/api/v1/projects/:projectId/mail/domains
Lists the shared domain and custom domains attached to this project, with claim, purchase, provisioning and DNS-check state.
- Use the claim response to publish ownership TXT; use the DNS verification action to refresh MX, SPF, DKIM and DMARC status.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "dnsRecords": { "type": "object", "properties": { "mx": { "type": "string" }, "spf": { "type": "string" }, "dkim": { "type": "string" }, "dmarc": { "type": "string" }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "required": [], "additionalProperties": false, "nullable": true }, "chargeMicroUsd": { "type": "string" }, "id": { "type": "string" }, "domain": { "type": "string" }, "claimToken": { "type": "string" }, "state": { "type": "string" }, "mailState": { "type": "string", "nullable": true }, "chargedAt": { "type": "string", "description": "Date string", "nullable": true }, "verifiedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "dnsRecords", "chargeMicroUsd", "id", "domain", "claimToken", "state", "mailState", "chargedAt", "verifiedAt" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": [ { "dnsRecords": { "mx": "string", "spf": "string", "dkim": "string", "dmarc": "string", "checks": null }, "chargeMicroUsd": "string", "id": "string", "domain": "string", "claimToken": "string", "state": "string", "mailState": "string", "chargedAt": "string", "verifiedAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTPurchase and provision a verified domainDetails +/api/v1/projects/:projectId/mail/domains/:domainId/add
Confirms the one-time $2 setup fee for the already verified claim, records the idempotent purchase, and provisions the domain in Mail.
- Incomplete DNS does not refund the setup fee. If Mail permanently cannot provision the paid domain, the platform compensates the charge and releases the claim.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "state": { "type": "string" }, "chargeMicroUsd": { "type": "string" }, "dnsRecords": { "type": "object", "properties": { "mx": { "type": "string" }, "spf": { "type": "string" }, "dkim": { "type": "string" }, "dmarc": { "type": "string" }, "checks": { "type": "object", "properties": { "mx": { "type": "boolean" }, "spf": { "type": "boolean" }, "dkim": { "type": "boolean" }, "dmarc": { "type": "boolean" } }, "required": [ "mx", "spf", "dkim", "dmarc" ], "additionalProperties": false } }, "required": [ "checks" ], "additionalProperties": false } }, "required": [ "id", "domain", "state", "chargeMicroUsd", "dnsRecords" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "domain": "string", "state": "string", "chargeMicroUsd": "string", "dnsRecords": { "mx": "string", "spf": "string", "dkim": "string", "dmarc": "string", "checks": { "mx": true, "spf": true, "dkim": true, "dmarc": true } } }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETERemove an owned custom domainDetails +/api/v1/projects/:projectId/mail/domains/:domainId/delete
Deletes the domain, its addresses and routing configuration from the tenant after owner authorization.
- The one-time setup fee is not refunded. Project deletion also requires explicit confirmation when paid domains remain.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "success": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCheck custom-domain DNS recordsDetails +/api/v1/projects/:projectId/mail/domains/:domainId/dns/verify
Performs a fresh check of the domain’s published MX, SPF, DKIM and DMARC records and returns each check separately.
- DNS resolvers may take time to observe changes. Retry after publishing records; a transient lookup error does not by itself mean a working domain should be disabled.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string" }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" } }, "ready": { "type": "boolean" } }, "required": [ "domain", "checks", "ready" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "domain": "string", "status": "string", "checks": null, "ready": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTChange a domain's sending planDetails +/api/v1/projects/:projectId/mail/domains/:domainId/sending-plan/change
purchase a paid plan now (an upgrade during a paid period charges the price difference), schedule a lower plan for the next period, or resume auto-renewal of the current plan. Returns the purchase id and status (pending until the new allowance is active).
- Requires the
project:editproject permission and billing access to the domain owner (the user, ororganization:billing:manage); otherwise403 BILLING_ACCESS_REQUIRED. idempotencyKey(8–128 characters fromA-Z a-z 0-9 : _ -) is required; reusing it with a different plan or action returns409 MAIL_IDEMPOTENCY_CONFLICT.- The domain must be verified (
409 MAIL_DOMAIN_UNVERIFIED); downgrades must useschedule(409 MAIL_USE_SCHEDULE_FOR_DOWNGRADE). 402 INSUFFICIENT_BALANCEwhen the wallet cannot cover the charge;409 MAIL_ACTIVATION_PENDINGwhile a previous change is activating.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
plan | scale | free | starter | growth | Yes |
action | schedule | purchase | resume | Yes |
idempotencyKey | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"enum": [
"scale",
"free",
"starter",
"growth"
]
},
"action": {
"type": "string",
"enum": [
"schedule",
"purchase",
"resume"
]
},
"idempotencyKey": {
"type": "string"
}
},
"required": [
"plan",
"action",
"idempotencyKey"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "status": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead a domain's sending planDetails +/api/v1/projects/:projectId/mail/domains/:domainId/sending-plan
Return the sending plan of a custom Mail domain: the plan catalog with allowances, prices and rate limits, the current plan, next plan, auto-renew, period, used and remaining messages, and whether plan changes are available (enabled). balanceMicroUsd is included only when you can manage the owner's billing.
- Requires the
project:readproject permission. - The shared free sending domain has no sending plan:
404 MAIL_DOMAIN_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "scale", "free", "starter", "growth" ] }, "allowance": { "type": "number" }, "priceMicroUsd": { "type": "string" }, "perMinute": { "type": "number" }, "perHour": { "type": "number" }, "perDay": { "type": "number" } }, "required": [ "plan", "allowance", "priceMicroUsd", "perMinute", "perHour", "perDay" ], "additionalProperties": false } }, "enabled": { "type": "boolean" }, "canManageBilling": { "type": "boolean" }, "plan": { "type": "string", "enum": [ "scale", "free", "starter", "growth" ] }, "nextPlan": { "type": "string", "nullable": true }, "autoRenew": { "type": "boolean" }, "status": { "type": "string" }, "lastError": { "type": "string", "nullable": true }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "used": { "type": "number" }, "remaining": { "type": "number" }, "allowance": { "type": "number" }, "usageAvailable": { "type": "boolean" }, "transition": { "type": "boolean" }, "renewalPriceMicroUsd": { "type": "string" }, "balanceMicroUsd": { "type": "string", "nullable": true }, "readiness": { "type": "object", "properties": { "ready": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "schema", "domain", "flag", "billing_functions", "rate_catalog", "mail_runtime", "scheduler", "scheduler_billing", "renewals" ] }, "ok": { "type": "boolean" }, "detail": { "type": "string" } }, "required": [ "id", "ok", "detail" ], "additionalProperties": false } } }, "required": [ "ready", "checks" ], "additionalProperties": false }, "rateUsage": { "type": "object", "properties": { "minute": { "type": "number" }, "hour": { "type": "number" }, "day": { "type": "number" } }, "required": [ "minute", "hour", "day" ], "additionalProperties": false, "nullable": true }, "billingOwnerType": { "type": "string", "enum": [ "user", "organization" ] }, "activation": { "type": "object", "properties": { "attempts": { "type": "number" }, "lastError": { "type": "string", "nullable": true }, "nextAttemptAt": { "type": "string", "nullable": true } }, "required": [ "attempts", "lastError", "nextAttemptAt" ], "additionalProperties": false, "nullable": true } }, "required": [ "plans", "enabled", "canManageBilling", "plan", "nextPlan", "autoRenew", "status", "lastError", "periodStart", "periodEnd", "used", "remaining", "allowance", "usageAvailable", "transition", "renewalPriceMicroUsd", "balanceMicroUsd", "readiness", "rateUsage", "billingOwnerType", "activation" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "plans": [ { "plan": "scale", "allowance": 0, "priceMicroUsd": "string", "perMinute": 0, "perHour": 0, "perDay": 0 } ], "enabled": true, "canManageBilling": true, "plan": "scale", "nextPlan": "string", "autoRenew": true, "status": "string", "lastError": "string", "periodStart": "string", "periodEnd": "string", "used": 0, "remaining": 0, "allowance": 0, "usageAvailable": true, "transition": true, "renewalPriceMicroUsd": "string", "balanceMicroUsd": "string", "readiness": { "ready": true, "checks": [ { "id": "schema", "ok": true, "detail": "string" } ] }, "rateUsage": { "minute": 0, "hour": 0, "day": 0 }, "billingOwnerType": "user", "activation": { "attempts": 0, "lastError": "string", "nextAttemptAt": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTVerify domain ownershipDetails +/api/v1/projects/:projectId/mail/domains/:domainId/verify
Checks the unique TXT challenge at _hubfly-mail.<domain> and reports whether the claim belongs to the project.
- This proves control of the domain for provisioning; it does not mean mail delivery DNS is ready.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domainId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "state": { "type": "string" } }, "required": [ "verified", "state" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "verified": true, "state": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }