Hubfly spaceDocs
Console

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

  1. Select REST or SMTP and the exact sender addresses the credential may use.
  2. Save the returned secret immediately. List operations never show it again.
  3. Send a test message from an authorized address, then inspect activity.
  4. Rotate or disable credentials promptly when access changes; revoke retired credentials.

Create a REST key for one sender

curl
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.

Open interactive API explorer
MethodPathPurpose
POST/api/v1/projects/:projectId/mail/credentials/createCreate a REST or SMTP credential
GET/api/v1/projects/:projectId/mail/credentialsList Mail credentials
DELETE/api/v1/projects/:projectId/mail/credentials/:credentialId/deleteRevoke a Mail credential
POST/api/v1/projects/:projectId/mail/credentials/:credentialId/rotateRotate a Mail credential
PUT/api/v1/projects/:projectId/mail/credentials/:credentialId/updateEnable or disable a Mail credential
POST/api/v1/projects/:projectId/mail/sendSubmit 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 aliases to the exact sender addresses this credential may use. allAddresses is an explicit domain-wide scope for owned custom domains; never enable it for the shared free domain.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
domainstringYes
namestringYes
kindrest | smtpYes
aliasesstring[]Yes
allAddressesbooleanNo
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 response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
credentialIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
credentialIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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: false to suspend access without deleting the credential; use revoke to remove it permanently.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
credentialIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
enabledbooleanNo
aliasesstring[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
fromstringYes
recipientsstring[]Yes
subjectstringYes
textstringYes
htmlstringNo
idempotencyKeystringYes
submittedAtstringNo
attachmentsobject[]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 response
    Response 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"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top