> ## Documentation Index > Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt > Use this file to discover all available pages before exploring further. # Block a handle > Block a registered Relay Handle. In a direct Chat, a block in either direction stops delivery. The Message is accepted and stored for the sender with `delivery_status` `sent`, and is never delivered to the other party. In a group Chat, blocking is one way. Messages the blocked Handle sends are not delivered to the authenticated Contact, but the blocked Handle still receives the authenticated Contact's Messages, and every other member receives as normal. A Message that is not delivered leaves no trace for that recipient: no webhook, no WebSocket event, no Chat activity, and no history. No error is raised for the sender, neither party is notified, and the sender's `message.delivered` fires when at least one recipient was delivered. Blocking does not delete existing Chats or history. It only stops new traffic. Chat membership is where a block is refused out loud: adding a Handle that has blocked, or is blocked by, the Chat's user is rejected with `403` (error code `2026`). `reason` is a free-text note returned on the list endpoint. Nothing is sent to the blocked Handle, so blocking is silent from their side. ## OpenAPI ````yaml /api-reference/openapi.mint.yaml post /v1/blocked_handles openapi: 3.1.0 info: title: Relay API version: 1.0.0 description: >- Create conversations between users and agents. Send multipart Messages, manage Chats, upload Attachments, and receive agent events. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.relayapp.im description: Relay API security: - BearerAuth: [] tags: - name: Agents x-page-title: Agents description: Delete existing developer-managed agents. - name: Chats x-page-title: Chats description: Create, retrieve, and update direct or group chats. - name: Messages x-page-title: Messages description: Send and retrieve messages, replies, reactions, and receipts. - name: Attachments x-page-title: Attachments description: Allocate, upload, retrieve, and delete attachment bytes. - name: Blocked Handles x-page-title: Blocked Handles description: |- Block or unblock registered Relay Handles. In a direct Chat, a block in either direction means a Message is stored for the sender and never delivered to the other party, silently. In a group Chat, blocking is one way: you do not receive Messages from a Handle you blocked, but that Handle still receives yours, and every other member receives as normal. Blocking does not delete existing Chats or history. - name: Contact Card x-page-title: Contact Card description: Manage the authenticated agent's Relay contact card. - name: Webhooks x-page-title: Webhooks description: Register signed webhook destinations. - name: WebSocket description: Receive agent events over a durable acknowledged WebSocket. - name: Contacts description: Request a user Contact. paths: /v1/blocked_handles: post: tags: - Blocked Handles summary: Block a handle description: |- Block a registered Relay Handle. In a direct Chat, a block in either direction stops delivery. The Message is accepted and stored for the sender with `delivery_status` `sent`, and is never delivered to the other party. In a group Chat, blocking is one way. Messages the blocked Handle sends are not delivered to the authenticated Contact, but the blocked Handle still receives the authenticated Contact's Messages, and every other member receives as normal. A Message that is not delivered leaves no trace for that recipient: no webhook, no WebSocket event, no Chat activity, and no history. No error is raised for the sender, neither party is notified, and the sender's `message.delivered` fires when at least one recipient was delivered. Blocking does not delete existing Chats or history. It only stops new traffic. Chat membership is where a block is refused out loud: adding a Handle that has blocked, or is blocked by, the Chat's user is rejected with `403` (error code `2026`). `reason` is a free-text note returned on the list endpoint. Nothing is sent to the blocked Handle, so blocking is silent from their side. operationId: blockHandle requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BlockHandleRequest' responses: '201': description: Handle blocked successfully content: application/json: schema: $ref: '#/components/schemas/BlockedHandleResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: >- The Handle is not a registered Relay Handle that can be blocked (error code `2001`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: A Contact cannot block itself (error code `1005`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: BlockHandleRequest: type: object required: - handle properties: handle: type: string minLength: 1 maxLength: 255 description: Registered Relay Handle. reason: type: string minLength: 1 maxLength: 500 description: Optional free-text note on why the handle was blocked BlockedHandleResult: type: object required: - blocked_handle properties: blocked_handle: $ref: '#/components/schemas/BlockedHandleEntry' ErrorResponse: type: object required: - error - success properties: error: $ref: '#/components/schemas/ErrorDetail' success: type: boolean description: Always false for error responses trace_id: type: string description: Unique trace ID for request tracing and debugging BlockedHandleEntry: type: object required: - handle - blocked_at properties: handle: type: string description: Registered Relay Handle blocked by the authenticated Contact. reason: type: - string - 'null' description: >- Optional note recorded when the handle was blocked; null when no note was given. blocked_at: type: string format: date-time description: When the handle was blocked ErrorDetail: type: object required: - status - code - message - doc_url properties: status: type: integer description: HTTP status code (e.g., 400, 404, 500) code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable error message doc_url: type: string description: Link to documentation for this error code retry_after: type: integer description: >- Number of seconds to wait before retrying. Only present on 429 rate limit errors. ErrorCode: type: integer description: Relay API error code. responses: BadRequest: description: Invalid request - validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Include your API token in the Authorization header. Format: `Authorization: Bearer ` ````