---
title: "Add a New Email Address"
method: POST
path: "/users/{user_id}/settings/emails/"
tags: ["Users"]
---

# Add a New Email Address

`POST /users/{user_id}/settings/emails/`

Adds a new unconfirmed email address to the user's account.
Once added, the system will send a confirmation email to the specified address.
#### Returns
Returns a JSON object with a `data` key containing the newly added (unconfirmed) email address.
#### Errors
If the request is unsuccessful, an `errors` key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.

## Path parameters

- `user_id` string, required

## Request body

- object
  - `data` object, required
    - `type` 'user-emails'
    - `attributes` object
      - `email_address` string — The new email address to add.

## Response `201`

The email address was successfully added and is pending confirmation.

- object
  - `id` string, required — The unique identifier of the user entity.
  - `type` string, required — The type identifier of the user entity (`users`).
  - `attributes` object, required — The properties of the user entity.
    - `active` boolean, required — Whether or not the user is an active user.
    - `date_registered` string, date-time, required — The time at which the user registered their account, as an iso8601 formatted timestamp.
    - `family_name` string — The family name of the user, used for bibliographic citations.
    - `full_name` string, required — The full name of the user, used for display on the OSF.
    - `given_name` string — The given name of the user, used for bibliographic citations.
    - `middle_names` string — The middle names of the user, used for bibliographic citations.
    - `suffix` string — The suffix of the user, used for bibliographic citations.
    - `locale` string — The user's locale, e.g. 'en_US'.
    - `timezone` string — The user's timezone, e.g. 'Etc/UTC'.
    - `social` object — A dictionary of the user's social and academic profile links. Fields may include: - `github`, `twitter`, `linkedIn`: List of profile URLs (strings) - `scholar`, `orcid`, `researcherId`, `impactStory`, etc.: Single URL string - `profileWebsites`: List of personal website URLs (strings)
    - `employment` object[] — A list of the user's employment history records.
      - `title` string
      - `institution` string, required
      - `department` string
      - `startYear` integer, required
      - `startMonth` integer, required
      - `endYear` integer
      - `endMonth` integer
      - `ongoing` boolean, required
    - `education` object[] — A list of the user's educational history records.
      - `degree` string
      - `institution` string, required
      - `department` string
      - `startYear` integer, required
      - `startMonth` integer, required
      - `endYear` integer
      - `endMonth` integer
      - `ongoing` boolean, required
  - `relationships` object, required — URLs to other entities or entity collections that have a relationship to the user entity.
    - `institutions` string — A link to the list of institutions the user is affiliated with.
    - `nodes` string — A link to the list of nodes the user is a contributor to.
  - `links` object, required — URLs to alternative representations of the user entity.
    - `html` string, URL — A link to the user's profile page on the OSF.
    - `profile_image` string, URL — A link to the user's profile image.

## Other responses

- `400` — Bad request. The email address is invalid or already exists on this user.
- `403` — Permission denied. You do not have permission to add an email for this user.
- `429` — Too many requests. You have exceeded the allowed number of email additions. Please wait and try again later.

---

[API](https://skmtc.net/osf/apis/osf-apiv2-documentation.md) · [All operations](https://skmtc.net/osf/apis/osf-apiv2-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/osf/osf-apiv2-documentation/versions/ca701048eb0d/schema)