> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update User Email — Shilo API Reference

> Update the email address for a Shilo user. This dedicated endpoint is separate from the general profile update. Requires a write-enabled API key.

Use this endpoint to change the email address associated with a Shilo user account. Email updates are handled through a dedicated endpoint — separate from the general profile update — because changing a user's email may trigger downstream notifications and identity-related processes within Shilo. This endpoint requires a **write-enabled** API key.

## Endpoint

```text theme={null}
PUT https://api.shilo.ai/api/v1/users/{identifier}/update_email
```

## Authentication

Include your write-enabled API key in the request header:

```text theme={null}
x-api-key: YOUR_API_KEY
```

## Path Parameters

<ParamField path="identifier" type="string" required>
  The identifier used to look up the user. Three formats are supported:

  | Format              | Example                                   |
  | ------------------- | ----------------------------------------- |
  | Plain Shilo UUID    | `ee6f2136-b94a-4438-9335-3acf5b2a0d31`    |
  | Prefixed Shilo UUID | `id:ee6f2136-b94a-4438-9335-3acf5b2a0d31` |
  | External user ID    | `external_user_id:agent-1`                |
</ParamField>

## Request Body

<ParamField body="existing_email" type="string" required>
  The user's current email address. Used to identify the account being updated.
</ParamField>

<ParamField body="updated_email" type="string" required>
  The new email address to assign to this user. Must be a valid email format.
</ParamField>

### Example Body

```json theme={null}
{
  "existing_email": "alex@example.com",
  "updated_email": "alex.new@example.com"
}
```

## Response

A successful request returns HTTP `200` with the full updated User object reflecting the new email address.

### Response Fields

<ResponseField name="id" type="string">
  The Shilo-assigned UUID for this user.
</ResponseField>

<ResponseField name="external_user_id" type="string">
  The user's external system ID.
</ResponseField>

<ResponseField name="name" type="string">
  Full display name of the user.
</ResponseField>

<ResponseField name="email" type="string">
  The updated primary email address of the user.
</ResponseField>

<ResponseField name="timezone" type="string">
  The user's configured timezone.
</ResponseField>

<ResponseField name="picture" type="string">
  URL of the user's profile picture.
</ResponseField>

<ResponseField name="created_date" type="string">
  ISO-8601 timestamp indicating when this user was created in Shilo.
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "external_user_id": "agent-1",
  "name": "Alex User",
  "email": "alex.new@example.com",
  "timezone": "America/New_York",
  "picture": "https://cdn.shilo.ai/avatars/ee6f2136.png",
  "created_date": "2024-01-15T09:00:00Z"
}
```

## Error Codes

| Status | Meaning                                                                                     |
| ------ | ------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body, missing `existing_email` or `updated_email`, or malformed identifier. |
| `403`  | Your API key is read-only. A write-enabled key is required.                                 |
| `404`  | No user found matching the provided identifier.                                             |

## Example Request

```bash theme={null}
curl -X PUT "https://api.shilo.ai/api/v1/users/ee6f2136-b94a-4438-9335-3acf5b2a0d31/update_email" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "existing_email": "alex@example.com",
    "updated_email": "alex.new@example.com"
  }'
```

### Using external user ID

```bash theme={null}
curl -X PUT "https://api.shilo.ai/api/v1/users/external_user_id:agent-1/update_email" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "existing_email": "alex@example.com",
    "updated_email": "alex.new@example.com"
  }'
```