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

# Update Email Settings

> Update email notification settings and manage subscribers for a scout.

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000/email-settings \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "skip_email": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      "https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000/email-settings",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"skip_email": True}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000/email-settings",
    {
      method: "PUT",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ skip_email: true })
    }
  );
  const data = await response.json();
  ```
</RequestExample>

## Overview

Manage email notification settings and subscriber lists for a scout. All fields are optional - provide only what you want to change.

## Permissions

* **Scout creators**: Can update all settings and manage all subscribers
* **Non-creators**: Can only unsubscribe themselves

## Use Cases

### 1. Toggle Email Notifications Only

Disable email notifications while keeping subscribers:

```bash Request theme={null}
curl --request PUT \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id}/email-settings \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "skip_email": true
  }'
```

```json Response theme={null}
{
  "scout_id": "123e4567-e89b-12d3-a456-426614174000",
  "skip_email": true,
  "message": "Email notifications disabled"
}
```

### 2. Add Subscribers Only

Subscribe multiple emails without changing notification settings:

```bash Request theme={null}
curl --request PUT \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id}/email-settings \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscribers_to_add": [
      "alice@example.com",
      "bob@example.com",
      "charlie@example.com"
    ]
  }'
```

```json Response theme={null}
{
  "scout_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscribers_added": [
    {"email": "alice@example.com", "status": "added"},
    {"email": "bob@example.com", "status": "already_subscribed"},
    {"email": "charlie@example.com", "status": "added"}
  ],
  "message": "Added 2 subscriber(s)"
}
```

### 3. Unsubscribe Yourself (Non-creator)

If you're not the scout creator, you can unsubscribe yourself:

```bash Request theme={null}
curl --request PUT \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id}/email-settings \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscribers_to_remove": ["your-email@example.com"]
  }'
```

```json Response theme={null}
{
  "scout_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscribers_removed": [
    {"email": "your-email@example.com", "status": "removed"}
  ],
  "message": "Removed 1 subscriber(s)"
}
```

### 4. Remove Multiple Subscribers (Creator Only)

Scout creators can remove any subscribers:

```bash Request theme={null}
curl --request PUT \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id}/email-settings \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscribers_to_remove": [
      "alice@example.com",
      "bob@example.com"
    ]
  }'
```

```json Response theme={null}
{
  "scout_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscribers_removed": [
    {"email": "alice@example.com", "status": "removed"},
    {"email": "bob@example.com", "status": "removed"}
  ],
  "message": "Removed 2 subscriber(s)"
}
```

### 5. Combined Update

Update multiple settings at once:

```bash Request theme={null}
curl --request PUT \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id}/email-settings \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "skip_email": false,
    "subscribers_to_add": ["newuser@example.com"],
    "subscribers_to_remove": ["olduser@example.com"]
  }'
```

```json Response theme={null}
{
  "scout_id": "123e4567-e89b-12d3-a456-426614174000",
  "skip_email": false,
  "subscribers_added": [
    {"email": "newuser@example.com", "status": "added"}
  ],
  "subscribers_removed": [
    {"email": "olduser@example.com", "status": "removed"}
  ],
  "message": "Email notifications enabled; Added 1 subscriber(s); Removed 1 subscriber(s)"
}
```

## Error Responses

### 403 Forbidden - Permission Denied

**Non-creator trying to add subscribers:**

```json theme={null}
{
  "detail": "Only scout creator can add subscribers"
}
```

**Non-creator trying to remove someone else:**

```json theme={null}
{
  "detail": "You can only unsubscribe yourself. Your email: your-email@example.com"
}
```

### 400 Bad Request - Validation Errors

**No fields provided:**

```json theme={null}
{
  "detail": "At least one field must be provided"
}
```

**Too many emails:**

```json theme={null}
{
  "detail": "Maximum 200 subscribers per request"
}
```

### 404 Not Found

```json theme={null}
{
  "detail": "Scout with id {scout_id} not found"
}
```

## Response Field Descriptions

### SubscriberResult Status Values

| Status               | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `added`              | Email was successfully subscribed                    |
| `removed`            | Email was successfully unsubscribed                  |
| `already_subscribed` | Email was already subscribed (not an error)          |
| `not_found`          | Email was not found in subscriber list (for removal) |
| `invalid`            | Email format is invalid                              |
| `permission_denied`  | User lacks permission to perform this operation      |

## Notes

* Email addresses are automatically normalized (lowercased and trimmed)
* Duplicate emails in a single request are automatically removed
* Adding an already-subscribed email returns `already_subscribed` status (not an error)
* Removing a non-existent subscription returns `not_found` status (not an error)
* Maximum 200 email addresses per request for `subscribers_to_add`
* All operations are idempotent - safe to retry


## OpenAPI

````yaml PUT /v1/scouting/tasks/{scout_id}/email-settings
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.yutori.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/scouting/tasks/{scout_id}/email-settings:
    put:
      tags:
        - Scouting
      summary: Update Email Settings
      description: Update email notification settings and manage subscribers for a scout.
      operationId: update_email_settings_v1_scouting_tasks__scout_id__email_settings_put
      parameters:
        - name: scout_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Scout Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailSettingsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailSettingsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UpdateEmailSettingsRequest:
      properties:
        skip_email:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Skip Email
          description: |2-

                    If true, email notifications will be skipped and only webhook notifications will be sent.
                    If false, both email and webhook notifications will be sent (default behavior).
                    
        subscribers_to_add:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Subscribers To Add
          description: >-
            List of email addresses to subscribe to this scout. Maximum 200 per
            request. Duplicates are automatically ignored.
        subscribers_to_remove:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Subscribers To Remove
          description: >-
            List of email addresses to unsubscribe from this scout. Non-creators
            can only remove themselves.
      type: object
      title: UpdateEmailSettingsRequest
    UpdateEmailSettingsResponse:
      properties:
        scout_id:
          type: string
          title: Scout Id
          description: The ID of the scout
        skip_email:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Skip Email
          description: Current skip_email setting, if updated
        subscribers_added:
          anyOf:
            - items:
                $ref: '#/components/schemas/SubscriberResult'
              type: array
            - type: 'null'
          title: Subscribers Added
          description: Results for each email address in subscribers_to_add
        subscribers_removed:
          anyOf:
            - items:
                $ref: '#/components/schemas/SubscriberResult'
              type: array
            - type: 'null'
          title: Subscribers Removed
          description: Results for each email address in subscribers_to_remove
        message:
          type: string
          title: Message
          description: Summary of changes made
      type: object
      required:
        - scout_id
        - message
      title: UpdateEmailSettingsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SubscriberResult:
      properties:
        email:
          type: string
          title: Email
          description: The email address
        status:
          type: string
          enum:
            - added
            - removed
            - already_subscribed
            - not_found
            - invalid
            - permission_denied
          title: Status
          description: Result status for this email operation
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Additional details about the result
      type: object
      required:
        - email
        - status
      title: SubscriberResult
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

````