feat: api v3 route to add email to user, optionally bypassing validation email, closes #11009

public/openapi/write/users/uid/emails.yaml

@@ -31,3 +31,54 @@ get:
                     items:
                       type: string
                       description: An email address
+post:
+  tags:
+    - users
+  summary: add email to user
+  description: |
+    This operation adds an email to the user account, optionally bypassing the confirmation step if requested.
+
+    **Note**: The confirmation bypass can only be called by super administrators or users with the `admin:users` privilege.
+  parameters:
+  - in: path
+    name: uid
+    schema:
+      type: integer
+    required: true
+    description: uid of the account to add the email
+    example: 1
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            email:
+              type: string
+              description: A single email address
+              example: test@example.org
+            skipConfirmation:
+              type: boolean
+              description: If truthy, will automatically confirm the user's email.
+              example: 1
+          required:
+            - email
+  responses:
+    '200':
+      description: email successfully added to user account
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  emails:
+                    type: array
+                    items:
+                      type: string
+                      description: An email address

src/controllers/write/users.js

@@ -253,6 +253,24 @@ Users.getInviteGroups = async function (req, res) {
 	return helpers.formatApiResponse(200, res, userInviteGroups.map(group => group.displayName));
 };
 
+Users.addEmail = async (req, res) => {
+	const canManageUsers = await privileges.admin.can('admin:users', req.uid);
+	const skipConfirmation = canManageUsers && req.body.skipConfirmation;
+
+	if (skipConfirmation) {
+		await user.setUserField(req.params.uid, 'email', req.body.email);
+		await user.email.confirmByUid(req.params.uid);
+	} else {
+		await api.users.update(req, {
+			uid: req.params.uid,
+			email: req.body.email,
+		});
+	}
+
+	const emails = await db.getSortedSetRangeByScore('email:uid', 0, 500, req.params.uid, req.params.uid);
+	helpers.formatApiResponse(200, res, { emails });
+};
+
 Users.listEmails = async (req, res) => {
 	const [isPrivileged, { showemail }] = await Promise.all([
 		user.isPrivileged(req.uid),

src/routes/write/users.js

@@ -48,6 +48,7 @@ function authenticatedRoutes() {
 	setupApiRoute(router, 'get', '/:uid/invites/groups', [...middlewares, middleware.assert.user], controllers.write.users.getInviteGroups);
 
 	setupApiRoute(router, 'get', '/:uid/emails', [...middlewares, middleware.assert.user], controllers.write.users.listEmails);
+	setupApiRoute(router, 'post', '/:uid/emails', [...middlewares, middleware.assert.user], controllers.write.users.addEmail);
 	setupApiRoute(router, 'get', '/:uid/emails/:email', [...middlewares, middleware.assert.user], controllers.write.users.getEmail);
 	setupApiRoute(router, 'post', '/:uid/emails/:email/confirm', [...middlewares, middleware.assert.user], controllers.write.users.confirmEmail);