diff --git a/data/web/api/openapi.yaml b/data/web/api/openapi.yaml
index 77c58b609..ee154c4da 100644
--- a/data/web/api/openapi.yaml
+++ b/data/web/api/openapi.yaml
@@ -185,6 +185,9 @@ paths:
               example:
                 username: info@domain.tld
                 domain: domain.tld
+                description: my time limited alias
+                validity: 8760
+                permanent: false
               properties:
                 username:
                   description: 'the mailbox an alias should be created for'
@@ -192,6 +195,15 @@ paths:
                 domain:
                   description: "the domain"
                   type: string
+                description:
+                  description: "a description for the alias, defaults to an empty string"
+                  type: string
+                validity:
+                  description: "how many hours the alias stays valid, 1 to 87600, defaults to 8760 (one year)"
+                  type: integer
+                permanent:
+                  description: "keep the alias after it expired, defaults to false"
+                  type: boolean
               type: object
       summary: Create time limited alias
   /api/v1/add/app-passwd:
diff --git a/data/web/inc/functions.mailbox.inc.php b/data/web/inc/functions.mailbox.inc.php
index a9f17705d..3a002864d 100644
--- a/data/web/inc/functions.mailbox.inc.php
+++ b/data/web/inc/functions.mailbox.inc.php
@@ -41,13 +41,15 @@ function mailbox($_action, $_type, $_data = null, $_extra = null) {
           else {
             $username = $_SESSION['mailcow_cc_username'];
           }
-          if (isset($_data["validity"]) && !filter_var($_data["validity"], FILTER_VALIDATE_INT, array('options' => array('min_range' => 1, 'max_range' => 87600)))) {
-            $_SESSION['return'][] = array(
-              'type' => 'danger',
-              'log' => array(__FUNCTION__, $_action, $_type, $_data_log, $_attr),
-              'msg' => 'validity_missing'
-            );
-            return false;
+          if (isset($_data["validity"])) {
+            if (!filter_var($_data["validity"], FILTER_VALIDATE_INT, array('options' => array('min_range' => 1, 'max_range' => 87600)))) {
+              $_SESSION['return'][] = array(
+                'type' => 'danger',
+                'log' => array(__FUNCTION__, $_action, $_type, $_data_log, $_attr),
+                'msg' => 'validity_missing'
+              );
+              return false;
+            }
           }
           else {
             // Default to 1 yr
@@ -60,7 +62,8 @@ function mailbox($_action, $_type, $_data = null, $_extra = null) {
             $permanent = 0;
           }
           $domain = $_data['domain'];
-          $description = $_data['description'];
+          // spamalias.description is NOT NULL, an absent description must not become a null insert
+          $description = $_data['description'] ?? '';
           $valid_domains[] = mailbox('get', 'mailbox_details', $username)['domain'];
           $valid_alias_domains = user_get_alias_details($username)['alias_domains'];
           if (!empty($valid_alias_domains)) {