API: single items, mailboxes, autoresponders and databases
The per-account API endpoints for one item of a collection, changing a mailbox or FTP account, autoresponders, and MariaDB and PostgreSQL databases, with examples.
The per-account collections are plural nouns (/mailboxes, /forwarders, /ftp-accounts, /ssl-certificates,
/ssh-keys, /dns-zones, /mysql-databases, /mysql-users, /postgres-databases, /cron-jobs, /uptime-monitors,
/backups). Each answers GET for one item, and the lists are paged (see the
REST conventions).
The paths name the account (/v1/accounts/{username}/…); the rules are those of every per-account endpoint. The REST conventions (paging, errors, Location) apply.
A=https://api.yourdomain.com/v1
H="Authorization: Bearer hf_xxx"
Lists and single items
| Method | Path | Who | What it does |
|---|---|---|---|
| GET | /v1/accounts/{username}/cron-jobs |
per account | The account's cron jobs |
| GET | /v1/accounts/{username}/cron-jobs/{id} |
per account | One of the account's cron jobs |
| GET | /v1/accounts/{username}/forwarders/{source} |
per account | One of the account's forwarders |
| GET | /v1/accounts/{username}/ftp-accounts |
per account | The account's ftp accounts |
| GET | /v1/accounts/{username}/ftp-accounts/{login} |
per account | One of the account's ftp accounts |
| GET | /v1/accounts/{username}/mailboxes/{address} |
per account | One of the account's mailboxes |
| GET | /v1/accounts/{username}/mysql-databases |
per account | The account's mysql databases |
| GET | /v1/accounts/{username}/mysql-databases/{database} |
per account | One of the account's mysql databases |
| GET | /v1/accounts/{username}/mysql-users |
per account | The account's mysql users |
| GET | /v1/accounts/{username}/mysql-users/{user} |
per account | One of the account's mysql users |
| GET | /v1/accounts/{username}/postgres-databases |
per account | The account's postgres databases |
| GET | /v1/accounts/{username}/postgres-databases/{database} |
per account | One of the account's postgres databases |
| GET | /v1/accounts/{username}/ssh-keys/{id} |
per account | One of the account's ssh keys |
| GET | /v1/accounts/{username}/ssl-certificates/{domain} |
per account | One of the account's ssl certificates |
| GET | /v1/accounts/{username}/usage |
staff | Disk, bandwidth, counts and resource usage against the limits |
GET /v1/accounts/{username}/usage
Query: period (the resource usage series: 24h (5-minute points, the default), 7d (hourly), 30d (4-hourly) or 1y (daily))
Changing a mailbox or an FTP account
| Method | Path | Who | What it does |
|---|---|---|---|
| PATCH | /v1/accounts/{username}/ftp-accounts/{login} |
per account, write | Change an FTP account's password and/or quota |
| PATCH | /v1/accounts/{username}/mailboxes/{address} |
per account, write | Change a mailbox's password, quota and/or whether it only sends |
PATCH /v1/accounts/{username}/ftp-accounts/{login}
| Field | Type | Required | Meaning |
|---|---|---|---|
password |
string | the new password | |
quota_mb |
integer | 0 = no limit (up to 1048576) |
PATCH /v1/accounts/{username}/mailboxes/{address}
| Field | Type | Required | Meaning |
|---|---|---|---|
password |
string | the new password | |
quota_mb |
integer | 0 = no limit (up to 102400) | |
send_only |
boolean | it sends, mail to it is refused |
Autoresponders
The autoresponder of a mailbox.
| Method | Path | Who | What it does |
|---|---|---|---|
| GET | /v1/accounts/{username}/autoresponders |
per account | The mailboxes that have an autoresponder |
| GET | /v1/accounts/{username}/autoresponders/{address} |
per account | A mailbox's autoresponder (enabled false when it has none) |
| PUT | /v1/accounts/{username}/autoresponders/{address} |
per account, write | Switch a mailbox's autoresponder on |
| DELETE | /v1/accounts/{username}/autoresponders/{address} |
per account, write | Switch a mailbox's autoresponder off |
PUT /v1/accounts/{username}/autoresponders/{address}
| Field | Type | Required | Meaning |
|---|---|---|---|
subject |
string | yes | the reply's subject |
body |
string | yes | the reply's text |
days |
integer | days before the same sender gets it again (default 1) | |
start |
string | first day, YYYY-MM-DD | |
end |
string | last day, YYYY-MM-DD |
Databases
MySQL and PostgreSQL together; engine picks one (mysql is the default). MongoDB stays at /v1/mongo.
| Method | Path | Who | What it does |
|---|---|---|---|
| GET | /v1/accounts/{username}/database-users |
per account | The account's MySQL users |
| POST | /v1/accounts/{username}/database-users |
per account, write | Create a MySQL user |
| GET | /v1/accounts/{username}/database-users/{name} |
per account | One MySQL user |
| DELETE | /v1/accounts/{username}/database-users/{name} |
per account, write | Delete a MySQL user |
| GET | /v1/accounts/{username}/databases |
per account | The account's MySQL and PostgreSQL databases together |
| POST | /v1/accounts/{username}/databases |
per account, write | Create a database (within the package's limit); postgres also makes its owner user and answers its password |
| GET | /v1/accounts/{username}/databases/{name} |
per account | One database |
| DELETE | /v1/accounts/{username}/databases/{name} |
per account, write | Delete a database and what is in it |
POST /v1/accounts/{username}/database-users
| Field | Type | Required | Meaning |
|---|---|---|---|
name |
string | yes | the name after the account's prefix |
password |
string | empty: a random one is made |
GET /v1/accounts/{username}/databases
Query: engine (only this engine)
POST /v1/accounts/{username}/databases
| Field | Type | Required | Meaning |
|---|---|---|---|
name |
string | yes | the name after the account's prefix |
engine |
one of mysql, postgres | mysql (default) or postgres | |
user |
boolean | mysql: also create a user of the same name |
GET /v1/accounts/{username}/databases/{name}
Query: engine (mysql or postgres (default: the first that has it))
DELETE /v1/accounts/{username}/databases/{name}
Query: engine (mysql (default) or postgres)