Mail API

Mail API

With the Mail API you create, change, deactivate and delete the mailboxes of your hosting automatically. You can also manage aliases and forwarding. It works on all our hosting servers (Linux and Windows) and is free of charge.

Step 1: Enable API access

Log in to admin.firestorm.ch with your FireStorm ID and enable API access under Account => Customer profile.

Step 2: Create a key with the scope “Mail”

In the same form, click Manage API keys. Enter a label, choose the scope Mail (mailboxes) and the hostings whose mailboxes the key may manage. Optionally restrict the key to individual domains of the hosting. We recommend also entering the IP addresses of your server: the key then only works from there.

The key is shown only once. Keep it in a safe place. For every new key with mail access we send you a confirmation by email. If you did not create the key yourself, revoke it immediately in the same window.

The main API key of the DNS API is deliberately not valid for the Mail API. This way a lost DNS key never opens your mailboxes.

Step 3: Use the API

Send the key in the X-API-Key header. Send data as JSON.

curl -H "X-API-Key: YOUR_API_KEY" https://api.firestorm.ch/mail/v1/domains

API endpoints

Base URL: https://api.firestorm.ch/mail/v1

Full technical description as an OpenAPI file: firestorm-mail-api.yaml

Examples

Create a mailbox

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"address":"anna@example.ch","password":"Secure-Pw-2026!","quota_mb":2048,"aliases":["anna.smith"]}' \
  https://api.firestorm.ch/mail/v1/mailboxes

Change password and storage

curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"password":"New-Pw-2026!","quota_mb":4096}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch

Set or switch off forwarding

The list replaces all previous targets. With "enabled":false and an empty list you switch forwarding off.

curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"forwarding":{"enabled":true,"addresses":["anna.private@example.org"]}}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch

Add and remove an alias

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"alias":"sales"}' https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch/aliases

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch/aliases/sales

Deactivate and reactivate

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch/disable

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"password":"Again-Pw-2026!"}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch/enable

Delete

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  "https://api.firestorm.ch/mail/v1/mailboxes/anna@example.ch?confirm=anna@example.ch"

Good to know

• Passwords: 10 to 30 characters, at least three of lower case, upper case, digits and special characters, must not contain the mailbox name. The API never returns passwords.
• Deactivating blocks the login (IMAP, POP3, SMTP, webmail). The content is kept, new emails keep arriving, aliases and forwarding stay active. To reactivate, you set a new password.
• Deleting removes the mailbox and all its emails permanently. That is why you have to confirm the address with confirm.
• Limits of your hosting (number of mailboxes, storage) also apply to the API. When a limit is reached, you get the error limit_reached.
• Mail service: if /domains shows "mail_service": false for a domain, the mail service of that domain is switched off in the hosting panel. Mailboxes will not work then.
• Windows hosting: password changes take effect within 2 minutes.
• Limits: 120 requests per minute per key, 100 new mailboxes and 500 changes per day per account. After 25 failed logins the IP address is blocked for 6 hours.
• Errors are returned as JSON: {"status":"error","error":"weak_password","message":"…"}. Evaluate the code in the error field in your program; the message text is meant for humans (German).