Mail API · Dashboard
Addresses, destinations & routes
Create receiving addresses, confirm destinations, and control exact or custom-domain routing rules.
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
- Check that the Mail workspace is ready.
- Create an address with a verified forwarding destination. Confirm any additional destination before using it.
- Create an exact rule for one address or a broader rule for an owned custom domain.
- Read the route list for the domain and verify priority and enabled state.
Create a free address
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/mail/addresses/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"address":"hello@free.hubmail.space","forwardTo":"owner@example.com"}'Replace the example alias with one available to your account and owner@example.com with your verified Hubfly space account email or a confirmed forwarding destination. An unverified destination returns FORWARD_DESTINATION_UNVERIFIED.
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 (12)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
POSTCreate a receiving addressDetails +/api/v1/projects/:projectId/mail/addresses/create
Creates a tenant-owned address and an exact-address forwarding route. Free addresses use @free.hubmail.space; custom-domain addresses require a domain already provisioned for this tenant.
- The destination must be the verified account email or a separately confirmed forwarding destination. The free allowance is five addresses per owner across projects.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
address | string | Yes |
forwardTo | string | No |
mailboxIds | string[] | No |
Complete request schema
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"forwardTo": {
"type": "string"
},
"mailboxIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"address"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "domain": { "type": "string" }, "destination": { "type": "string" }, "kind": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "mailboxIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "email", "domain", "destination", "kind", "active", "created_at", "mailboxIds" ], "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": { "email": "string", "domain": "string", "destination": "string", "kind": "string", "active": true, "created_at": "string", "mailboxIds": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList project addressesDetails +/api/v1/projects/:projectId/mail/addresses
Lists the active receiving addresses owned by this Mail project, including the domain, forwarding destination and address kind.
- The response does not contain message bodies. Mail delivered into mailboxes is read in the mail client or through the Mailbox API.
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": { "email": { "type": "string" }, "domain": { "type": "string" }, "destination": { "type": "string" }, "mailboxes": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "email", "domain", "destination", "kind", "active", "created_at" ], "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": [ { "email": "string", "domain": "string", "destination": "string", "mailboxes": [ "string" ], "kind": "string", "active": true, "created_at": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a receiving addressDetails +/api/v1/projects/:projectId/mail/addresses/:address/delete
Removes an address and its associated tenant forwarding route.
- Address deletion is immediate for new inbound mail. Confirm the encoded address path value is URL-encoded.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
address | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "success": { "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" } }
POSTRequest a forwarding-destination confirmationDetails +/api/v1/projects/:projectId/mail/forwarding-destinations/create
Sends a confirmation code to a new destination email address. The destination remains inactive until verified.
- The verified account email is available by default. A destination cannot receive forwarded messages until confirmation succeeds.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
email | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"email": {
"type": "string"
}
},
"required": [
"email"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "email": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "verified", "email" ], "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, "email": "string", "expiresAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList forwarding destinationsDetails +/api/v1/projects/:projectId/mail/forwarding-destinations
Lists the project’s default and additional forwarding destinations with their confirmation status.
- Only confirmed destinations can be assigned to forwarding rules.
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": { "defaultEmail": { "type": "string", "nullable": true }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "additionalProperties": false } } }, "required": [ "defaultEmail", "destinations" ], "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": { "defaultEmail": "string", "destinations": [ { "email": "string", "status": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTConfirm a forwarding destinationDetails +/api/v1/projects/:projectId/mail/forwarding-destinations/verify
Verifies the one-time code sent to the destination and activates that address for routing.
- Codes expire; request a new confirmation if the code is no longer valid.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
email | string | Yes |
code | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"email",
"code"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "email": { "type": "string" } }, "required": [ "verified", "email" ], "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, "email": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead Mail project statusDetails +/api/v1/projects/:projectId/mail
Returns the project’s Mail tenant identity, owner type, owner ID, service group and provisioning status.
- Use this endpoint to distinguish a ready workspace from a project whose Mail tenant has not finished provisioning.
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": { "id": { "type": "string" }, "owner_type": { "type": "string" }, "owner_id": { "type": "string" }, "group_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "owner_type", "owner_id", "group_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", "owner_type": "string", "owner_id": "string", "group_id": "string", "status": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate an inbound routing ruleDetails +/api/v1/projects/:projectId/mail/routes/create
Creates a route for an owned domain. Rules support exact, wildcard/catch-all and regular-expression local-part matching, priority, forward/reject/discard actions, and header conditions.
- Forward destinations must already be verified. Free-domain projects may manage only their own exact-address rules; domain-wide patterns are for owned custom domains.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
domain | string | Yes |
match_type | string | Yes |
pattern | string | Yes |
priority | number | Yes |
action | string | Yes |
destinations | string[] | Yes |
header_conditions | object[] | No |
enabled | boolean | No |
Complete request schema
{
"type": "object",
"properties": {
"domain": {
"type": "string"
},
"match_type": {
"type": "string"
},
"pattern": {
"type": "string"
},
"priority": {
"type": "number"
},
"action": {
"type": "string"
},
"destinations": {
"type": "array",
"items": {
"type": "string"
}
},
"header_conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"regex": {
"type": "string"
}
},
"required": [
"name",
"regex"
],
"additionalProperties": false
}
},
"enabled": {
"type": "boolean"
}
},
"required": [
"domain",
"match_type",
"pattern",
"priority",
"action",
"destinations"
],
"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" }, "match_type": { "type": "string" }, "pattern": { "type": "string" }, "priority": { "type": "number" }, "action": { "type": "string" }, "destinations": { "type": "array", "items": { "type": "string" } }, "header_conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "regex": { "type": "string" } }, "required": [ "name", "regex" ], "additionalProperties": false } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "domain", "match_type", "pattern", "priority", "action", "destinations", "header_conditions", "enabled", "created_at", "updated_at" ], "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", "match_type": "string", "pattern": "string", "priority": 0, "action": "string", "destinations": [ "string" ], "header_conditions": [ { "name": "string", "regex": "string" } ], "enabled": true, "created_at": "string", "updated_at": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList routing rules for a domainDetails +/api/v1/projects/:projectId/mail/routes
Returns rules for the requested tenant-owned domain, ordered for evaluation with patterns, priority, action, destinations and conditions.
- Pass the
domainquery parameter. Patterns apply to the local part before@; rule conditions and matching behavior are described in the Mail guide.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domain | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "match_type": { "type": "string" }, "pattern": { "type": "string" }, "priority": { "type": "number" }, "action": { "type": "string" }, "destinations": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } }, "required": [ "id", "domain", "match_type", "pattern", "priority", "action", "destinations", "enabled" ], "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", "match_type": "string", "pattern": "string", "priority": 0, "action": "string", "destinations": [ "string" ], "enabled": true } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTTest mail routingDetails +/api/v1/projects/:projectId/mail/routes/test
Evaluate how an inbound message to address, with optional test headers, would be routed. Returns the resulting action, destinations, matched route_ids and a reason.
- Requires the
project:readproject permission on a Mail project. - An address or headers the mail service rejects return
MAIL_ROUTING_TEST_FAILEDwith the service's 4xx status (502 for server errors).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
address | string | Yes |
headers | object | No |
Complete request schema
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"address"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "address": { "type": "string" }, "action": { "type": "string" }, "destinations": { "type": "array", "items": { "type": "string" } }, "route_ids": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } }, "required": [ "address", "action", "destinations", "route_ids", "reason" ], "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": { "address": "string", "action": "string", "destinations": [ "string" ], "route_ids": [ "string" ], "reason": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete an inbound routing ruleDetails +/api/v1/projects/:projectId/mail/routes/:routeId/delete
Removes one route from the tenant.
- Deleting an exact free-domain route stops forwarding for that address; delete the address itself when you want to release it.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
routeId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "success": { "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" } }
PUTUpdate an inbound routing ruleDetails +/api/v1/projects/:projectId/mail/routes/:routeId/update
Changes the priority, action, destinations, header conditions or enabled state of one route.
- Priority zero is valid. Supplied destination lists replace the previous list; only verified destinations can be used.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
routeId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
priority | number | No |
action | string | No |
destinations | string[] | No |
header_conditions | object[] | No |
enabled | boolean | No |
Complete request schema
{
"type": "object",
"properties": {
"priority": {
"type": "number"
},
"action": {
"type": "string"
},
"destinations": {
"type": "array",
"items": {
"type": "string"
}
},
"header_conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"regex": {
"type": "string"
}
},
"required": [
"name",
"regex"
],
"additionalProperties": false
}
},
"enabled": {
"type": "boolean"
}
},
"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" }, "match_type": { "type": "string" }, "pattern": { "type": "string" }, "priority": { "type": "number" }, "action": { "type": "string" }, "destinations": { "type": "array", "items": { "type": "string" } }, "header_conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "regex": { "type": "string" } }, "required": [ "name", "regex" ], "additionalProperties": false } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "domain", "match_type", "pattern", "priority", "action", "destinations", "header_conditions", "enabled", "created_at", "updated_at" ], "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", "match_type": "string", "pattern": "string", "priority": 0, "action": "string", "destinations": [ "string" ], "header_conditions": [ { "name": "string", "regex": "string" } ], "enabled": true, "created_at": "string", "updated_at": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }