> ## Documentation Index > Fetch the complete documentation index at: https://docs.emailx.ai/llms.txt > Use this file to discover all available pages before exploring further. # Check which contacts can be reached > Checks up to 5,000 contacts, by ID or filter, and tells you which ones are eligible for outreach. Nothing changes. Permission: `contacts:read` [Read the recovery rules](https://docs.emailx.ai/en/api-reference/idempotency.md) before retrying a write. Keep the same key and body for the same logical operation. ## OpenAPI ````yaml openapi/emailx.en.json POST /workspaces/{workspace_id}/contacts/selection openapi: 3.0.3 info: title: Emailx API version: 1.0.0-beta description: >- Customer and agency integrations for Emailx. Beta access is operator-issued. The v1 beta supports bounded People CSV/XLSX imports, saved email-template settings, selected email generation with explicit AI-credit confirmation, exact-message approval, reviewed email activation for native scheduled sending, and explicitly confirmed inbox replies bound to saved context when host capabilities permit. Inbox context is bounded and may be incomplete or stale; no provider refresh occurs. Manual LinkedIn imports, reviewed activation and reviewed resume of paused campaigns are separate gated workflows. Reply drafts, knowledge, team, infrastructure quotes with hosted checkout and agency administration are covered by separate scopes. Signed webhooks report durable operation outcomes. It does not support immediate batches or direct card charges. servers: - url: https://app.emailx.ai/api/v1 description: Emailx application ยท access must be enabled security: [] tags: - name: Getting started - name: Workspaces - name: Contacts - name: Templates - name: Campaigns - name: Inbox - name: Senders - name: Team - name: Analytics - name: Imports - name: Operations - name: Knowledge - name: Infrastructure - name: Agency paths: /workspaces/{workspace_id}/contacts/selection: post: tags: - Import contacts summary: Check which contacts can be reached description: >- Checks up to 5,000 contacts, by ID or filter, and tells you which ones are eligible for outreach. Nothing changes. Permission: `contacts:read` operationId: select_api_people parameters: - name: workspace_id in: path required: true schema: type: integer minimum: 1 description: Emailx workspace (Clients) ID, not the agency workspace link ID. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.:/-]+$ description: Unique per logical mutation. Same path and body replay for 24 hours. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SelectPeople' example: channel: email filters: company: Example Studio location: Milano responses: '200': description: Success headers: X-Request-Id: schema: type: string Emailx-Api-Version: schema: type: string X-RateLimit-Limit: schema: type: string X-RateLimit-Remaining: schema: type: string X-RateLimit-Reset: schema: type: string content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PeopleSelection' required: - data example: data: channel: linkedin people: - id: 123 eligible: true blockers: [] eligible_ids: - 123 selection_fingerprint: >- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa '400': description: Request error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid, expired or revoked API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient scope or write permission content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Resource missing or inaccessible content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict, concurrent request or uncertain original result content: application/json: schema: $ref: '#/components/schemas/Error' headers: Retry-After: schema: type: string description: Seconds to wait when present. '413': description: Request error content: application/json: schema: $ref: '#/components/schemas/Error' '415': description: Request error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited; respect Retry-After content: application/json: schema: $ref: '#/components/schemas/Error' headers: Retry-After: schema: type: string description: Seconds to wait when present. '500': description: Request error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: API disabled, request storage unavailable or feature not enabled content: application/json: schema: $ref: '#/components/schemas/Error' headers: Retry-After: schema: type: string description: Seconds to wait when present. security: - BearerAuth: [] x-codeSamples: - lang: cURL source: >- curl -X POST "https://app.emailx.ai/api/v1/workspaces/123/contacts/selection" \ -H "Authorization: Bearer $EMAILX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: example-operation-001" \ --data '{"channel":"email","filters":{"company":"Example Studio","location":"Milano"}}' - lang: Python source: |- import os, requests response = requests.post( "https://app.emailx.ai/api/v1/workspaces/123/contacts/selection", headers={"Authorization": "Bearer " + os.environ["EMAILX_API_KEY"], "Idempotency-Key": "example-operation-001"}, json={'channel': 'email', 'filters': {'company': 'Example Studio', 'location': 'Milano'}}, timeout=30, ) response.raise_for_status() print(response.json()) - lang: JavaScript source: >- const response = await fetch("https://app.emailx.ai/api/v1/workspaces/123/contacts/selection", { method: "POST", headers: { Authorization: `Bearer ${process.env.EMAILX_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "example-operation-001" }, body: JSON.stringify({"channel": "email", "filters": {"company": "Example Studio", "location": "Milano"}}), signal: AbortSignal.timeout(30000), }); if (!response.ok) throw new Error(`Emailx: ${response.status}`); console.log(await response.json()); components: schemas: SelectPeople: type: object properties: channel: type: string enum: - email - linkedin default: email contact_ids: type: array items: type: integer minimum: 1 minItems: 1 maxItems: 5000 uniqueItems: true filters: type: object properties: name: type: string minLength: 1 maxLength: 200 company: type: string minLength: 1 maxLength: 200 title: type: string minLength: 1 maxLength: 200 location: type: string minLength: 1 maxLength: 200 email: type: string minLength: 1 maxLength: 200 minProperties: 1 additionalProperties: false additionalProperties: false oneOf: - required: - contact_ids not: required: - filters - required: - filters not: required: - contact_ids description: >- Read-only selection preview. Provide exactly one of contact_ids or filters; no contact is changed. PeopleSelection: type: object properties: channel: type: string enum: - email - linkedin people: type: array items: type: object properties: id: type: integer minimum: 1 eligible: type: boolean blockers: type: array items: type: string required: - id - eligible - blockers eligible_ids: type: array items: type: integer minimum: 1 selection_fingerprint: type: string pattern: ^[a-f0-9]{64}$ required: - channel - people - eligible_ids - selection_fingerprint Error: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string details: type: object additionalProperties: true required: - code - message - request_id required: - error securitySchemes: BearerAuth: type: http scheme: bearer description: >- ex_test_ or ex_live_ key issued by an Emailx operator. Never use provider keys or session cookies. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.