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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/api/schedule-recipients/manage-email-only-user",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Manage email-only user

Creates or updates an [email-only user](/share/deliveries/email). An email-only user is a recipient of a delivery that isn't associated with an Omni account.

If Omni matches the provided email to an existing email-only user, the user will be updated according to the `userAttributes` in the request body.

<Tip>
  Need to include multiple email-only users? Use the [Create or update multiple email-only users](/api/schedule-recipients/bulk-manage-email-only-users) endpoint.
</Tip>


## OpenAPI

````yaml /api/openapi.yaml post /v1/users/email-only
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: AI
    description: AI-powered query generation
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Labels
    description: >
      Manage labels in an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - name: Folders
    description: Create and organize content folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/users/email-only:
    post:
      tags:
        - Schedule recipients
      summary: Manage email-only user
      operationId: manageEmailOnlyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: The user's email address.
                userAttributes:
                  type: object
                  description: >
                    An object defining the user's [user
                    attributes](/administration/users/attributes). Attributes
                    are represented as key/value pairs, where the keys map to
                    the IDs of user attributes (the **Reference** column in the
                    **User attributes** page) defined in Omni.


                    When providing user attributes, note that:


                    - `omni_user_timezone` is the only supported system
                    attribute

                    - **Values must match the user attribute's specified type**.
                    For example, `number` attribute values must be numbers such
                    as `1`, `10`, etc.

                    - **Multi-value attributes should be provided using
                    arrays**. For example: `["US","EU"]` or `[1, 10]`


                    To unset attributes:


                    - `null` values

                    - `""` - Empty strings for string attributes

                    - `[]` - Empty arrays for multi-value attributes
            examples:
              basic:
                summary: Basic request
                value:
                  email: iamagoodblob@blobsrus.co
              withAttributes:
                summary: Set user attributes
                value:
                  email: iamagoodblob@blobsrus.co
                  userAttributes:
                    region:
                      - US
                      - EU
                    omni_user_timezone: America/New_York
                    is_admin: 0
                    is_sales_team: 1
              unsetAttributes:
                summary: Unset user attributes
                value:
                  email: iamagoodblob@blobsrus.co
                  userAttributes:
                    is_admin: null
                    is_sales_team: ''
                    region: []
      responses:
        '200':
          description: Email-only user created or updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                    description: The email address of the created or updated user.
                  userId:
                    type: string
                    format: uuid
                    description: The unique identifier of the email-only user.
              example:
                email: iamagoodblob@blobsrus.co
                userId: 9e8719d9-276a-4964-9395-a493189a247c
        '400':
          description: >
            Bad Request. Possible error messages include:


            - `Invalid JSON`

            - `email: email is required`

            - `email: Invalid email address`

            - `The provided user attributes: "<attribute>" do not match the
            names of existing user attributes.`

            - `User Attribute <attribute> is type number, but passed-in value
            <value> is not a number.`

            - `The timezone <invalidTimezone> is not supported. Please see the
            connection page or [user profile
            page](/administration/users/your-account) for the list of valid
            timezones. Use e.g. "America/New_York" instead of "EST"`

            - `User Attribute <attribute> has multiple values enabled, but the
            passed-in value is not an array. If passing a single value for a
            user attribute with multiple values enabled, please wrap the value
            in an array [x].`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - orgApiKey: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    MethodNotAllowed:
      description: Method Not Allowed - Invalid HTTP method for this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#personal-access-tokens-pat).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````