> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Set preferred email (bulk) > Star a stored email as preferred for one or many persons. Campaign enrollment uses the preferred email when it is set. The email must already exist on each person — this endpoint does not add new addresses. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins. For a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-email`. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/preferred-email openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/persons/preferred-email: post: tags: - Persons summary: Set preferred email (bulk) description: >- Star a stored email as preferred for one or many persons. Campaign enrollment uses the preferred email when it is set. The email must already exist on each person — this endpoint does not add new addresses. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins. For a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-email`. operationId: setPersonsPreferredEmail requestBody: content: application/json: schema: $ref: '#/components/schemas/SetPreferredEmailsBulkRequest' responses: '200': description: Preferred emails updated content: application/json: schema: $ref: '#/components/schemas/SetPreferredEmailsBulkResponse' example: success: true data: updated: - person_id: 123e4567-e89b-12d3-a456-426614174000 preferred_email: john@gmail.com failed: - person_id: 00000000-0000-0000-0000-000000000001 error: Person not found '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: SetPreferredEmailsBulkRequest: type: object properties: updates: type: array items: type: object properties: person_id: type: string format: uuid description: Person UUID. Get IDs from POST /v1/persons/search. email: type: string minLength: 1 description: >- Email address to star as preferred. Must already exist on that person. required: - person_id - email minItems: 1 maxItems: 100 description: >- Persons to update (1–100). Invalid rows fail individually and do not block other rows. When the same person_id appears twice, the last entry wins. required: - updates SetPreferredEmailsBulkResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/SetPreferredEmailsBulkResult' required: - success - data SetPreferredEmailsBulkResult: type: object properties: updated: type: array items: type: object properties: person_id: type: string format: uuid preferred_email: type: string required: - person_id - preferred_email description: >- Persons whose preferred email was set. preferred_email is the stored address that was starred. failed: type: array items: type: object properties: person_id: type: string format: uuid description: Person UUID that failed. error: type: string description: >- Why this row was not updated, such as "Person not found" or "Email is not stored on this person". required: - person_id - error description: >- Rows that could not be updated. Other valid rows in the same request are still processed. required: - updated - failed securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````