Mail API · Dashboard
Credentials & Dashboard sending
Create, scope, rotate, disable, or revoke REST and SMTP credentials; submit a project test message.
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
- Select REST or SMTP and the exact sender addresses the credential may use.
- Save the returned secret immediately. List operations never show it again.
- Send a test message from an authorized address, then inspect activity.
- Rotate or disable credentials promptly when access changes; revoke retired credentials.
Create a REST key for one sender
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/mail/credentials/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain":"free.hubmail.space","name":"transactional","kind":"rest","aliases":["hello@free.hubmail.space"]}'Replace the example alias with an address already owned by this project. The returned REST key is shown once; store it before leaving the response.
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 (6)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/mail/credentials/create | Create a REST or SMTP credential |
| GET | /api/v1/projects/:projectId/mail/credentials | List Mail credentials |
| DELETE | /api/v1/projects/:projectId/mail/credentials/:credentialId/delete | Revoke a Mail credential |
| POST | /api/v1/projects/:projectId/mail/credentials/:credentialId/rotate | Rotate a Mail credential |
| PUT | /api/v1/projects/:projectId/mail/credentials/:credentialId/update | Enable or disable a Mail credential |
| POST | /api/v1/projects/:projectId/mail/send | Submit a transactional message from the Dashboard |
POSTCreate a REST or SMTP credentialDetails +/api/v1/projects/:projectId/mail/credentials/create
Creates an independent REST API key or SMTP login for the selected domain and sender-address scope. The raw secret is returned only when created.
- Set
aliasesto the exact sender addresses this credential may use.allAddressesis an explicit domain-wide scope for owned custom domains; never enable it for the shared free domain.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
domain | string | Yes |
name | string | Yes |
kind | rest | smtp | Yes |
aliases | string[] | Yes |
allAddresses | boolean | No |
Complete request schema
{
"type": "object",
"properties": {
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"rest",
"smtp"
]
},
"aliases": {
"type": "array",
"items": {
"type": "string"
}
},
"allAddresses": {
"type": "boolean"
}
},
"required": [
"domain",
"name",
"kind",
"aliases"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "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 Mail credentialsDetails +/api/v1/projects/:projectId/mail/credentials
Lists project credentials and their kind, allowed sender addresses and enabled status. Secret values are omitted.
- Use rotate to replace a secret or update to disable it. Copy secrets at creation because they cannot be retrieved later.
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": { "id": { "type": "string" }, "domain": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "enabled": { "type": "boolean" }, "aliases": { "type": "array", "items": { "type": "string" } }, "per_minute": { "type": "number" }, "per_hour": { "type": "number" }, "per_day": { "type": "number" } }, "required": [ "id", "domain", "name", "kind", "enabled", "aliases", "per_minute", "per_hour", "per_day" ], "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", "name": "string", "kind": "string", "enabled": true, "aliases": [ "string" ], "per_minute": 0, "per_hour": 0, "per_day": 0 } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETERevoke a Mail credentialDetails +/api/v1/projects/:projectId/mail/credentials/:credentialId/delete
Permanently revokes a REST or SMTP credential so it can no longer authenticate.
- Revocation cannot be undone. Create a replacement credential if a service still needs access.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
credentialId | 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" } }
POSTRotate a Mail credentialDetails +/api/v1/projects/:projectId/mail/credentials/:credentialId/rotate
Replaces a credential’s secret while keeping its ID and sender scope. The prior secret stops working immediately.
- Deploy the returned replacement secret to your application before retrying requests with it.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
credentialId | 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", "additionalProperties": { "type": "string" } }, "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" } }
PUTEnable or disable a Mail credentialDetails +/api/v1/projects/:projectId/mail/credentials/:credentialId/update
Changes whether an existing REST or SMTP credential may authenticate.
- Send
enabled: falseto suspend access without deleting the credential; use revoke to remove it permanently.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
credentialId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
enabled | boolean | No |
aliases | string[] | No |
Complete request schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"aliases": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [],
"additionalProperties": false
}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" } }
POSTSubmit a transactional message from the DashboardDetails +/api/v1/projects/:projectId/mail/send
Submits an individual message through the project’s private tenant route, applying the same sender ownership, recipient allowance, message validation and durable queue as direct REST and SMTP.
- Use no more than 10 recipients per request. Composer requests are limited by the Dashboard request body-size budget; attachments are limited to 5 MB total.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
from | string | Yes |
recipients | string[] | Yes |
subject | string | Yes |
text | string | Yes |
html | string | No |
idempotencyKey | string | Yes |
submittedAt | string | No |
attachments | object[] | No |
Complete request schema
{
"type": "object",
"properties": {
"from": {
"type": "string"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
}
},
"subject": {
"type": "string"
},
"text": {
"type": "string"
},
"html": {
"type": "string"
},
"idempotencyKey": {
"type": "string"
},
"submittedAt": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"contentType": {
"type": "string"
},
"contentBase64": {
"type": "string"
}
},
"required": [
"filename",
"contentType",
"contentBase64"
],
"additionalProperties": false
}
}
},
"required": [
"from",
"recipients",
"subject",
"text",
"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" } }