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

# Opt out a phone number or email

> Opts out a phone number or email address, even if it doesn't belong to a contact yet. Sends to that address are rejected with `403 RECIPIENT_SUPPRESSED`.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/contacts/suppressions
openapi: 3.1.0
info:
  title: Blujay API
  version: 1.0.0
  description: >-
    The Blujay API lets you send and receive iMessage, RCS and SMS messages from
    your

    Blujay phone numbers, manage contacts, and receive real-time webhooks.


    Every response uses the same JSON envelope and carries a `trace_id` you can
    share

    with support. Authenticate with your workspace API key.
servers:
  - url: https://api.blujay.io
    description: Production
security:
  - PublicApiKey: []
tags:
  - name: Auth
    description: Check which workspace and credential a request is using.
  - name: Chats
    description: >-
      Direct and group conversations between your Blujay numbers and your
      contacts.
  - name: Messages
    description: Send, read, edit, unsend and retry messages.
  - name: Phone Numbers
    description: >-
      Your Blujay numbers, whether each can send right now, and their live
      sending limits.
  - name: Capability
    description: >-
      Check whether a phone number can be reached by iMessage, RCS or SMS before
      you send.
  - name: Contacts
    description: Create, find, update, tag, assign and opt out contacts.
  - name: vCards
    description: >-
      Saved contact cards that you can send in a message. Recipients get a
      native contact card over iMessage, SMS or RCS.
  - name: Team Members
    description: People in your workspace you can assign contacts to.
  - name: Workflows
    description: Enroll contacts in workflows you start manually.
  - name: Attachments
    description: >-
      Upload files once and reuse them in messages, or download files from
      messages.
  - name: Webhooks
    description: Subscribe to events, inspect delivery attempts and verify signatures.
paths:
  /v1/contacts/suppressions:
    post:
      tags:
        - Contacts
      summary: Opt out a phone number or email
      description: >-
        Opts out a phone number or email address, even if it doesn't belong to a
        contact yet. Sends to that address are rejected with `403
        RECIPIENT_SUPPRESSED`.
      operationId: createPublicContactSuppression
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicContactSuppressionInput'
            examples:
              suppressPhone:
                summary: Opt out a phone number
                value:
                  address: '+15555550123'
                  reason: requested_stop
      responses:
        '200':
          description: The opted-out address.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/XTraceID'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PublicContactSuppression'
      security:
        - PublicApiKey: []
components:
  schemas:
    PublicContactSuppressionInput:
      type: object
      additionalProperties: false
      required:
        - address
      properties:
        address:
          type: string
          examples:
            - '+15555550123'
        reason:
          type: string
          examples:
            - Asked to stop receiving texts
    SuccessEnvelope:
      type: object
      description: Wraps every successful response. The result is in `data`.
      required:
        - status
        - trace_id
        - timestamp
      properties:
        status:
          type: string
          enum:
            - success
        trace_id:
          $ref: '#/components/schemas/TraceId'
        timestamp:
          type: string
          examples:
            - '2026-10-14T17:01:00.000Z'
          format: date-time
        client_request_id:
          type: string
          description: >-
            Your `X-Request-ID` header value, echoed back when you send one. Not
            included on the send responses (`POST /v1/chats`, `POST
            /v1/chats/{chat_id}/messages`, `POST
            /v1/messages/{message_id}/retry`); keep your own mapping from your
            request ID to the returned message ID there.
    PublicContactSuppression:
      type: object
      additionalProperties: false
      required:
        - address_type
        - address
        - opted_out
        - opted_out_at
        - opted_out_source
      properties:
        address_type:
          type: string
          enum:
            - phone
            - email
        address:
          type: string
          examples:
            - '+15555550123'
        opted_out:
          type: boolean
          const: true
        opted_out_at:
          type: string
          examples:
            - '2026-10-14T17:01:00.000Z'
          format: date-time
        opted_out_source:
          type: string
          examples:
            - api
        reason:
          type: string
          examples:
            - Asked to stop receiving texts
    TraceId:
      type: string
      examples:
        - trc_8f2a1c0e4b7d
      pattern: ^trc_[A-Za-z0-9_-]+$
  headers:
    XTraceID:
      description: >-
        Unique ID for this request. It matches `trace_id` in the body. Include
        it when you contact Blujay support.
      schema:
        $ref: '#/components/schemas/TraceId'
  securitySchemes:
    PublicApiKey:
      type: http
      scheme: bearer
      bearerFormat: blu_...
      description: >
        Your workspace API key, sent as `Authorization: Bearer blu_...`.
        Workspace admins can find it in the Blujay app under **API**.


        An API key has full access to your workspace and works on every
        endpoint. There is no test mode: every key sends real messages and
        changes real data, so keep it secret and use it only from your server.


        Each API key can make 600 read requests and 120 write requests per
        minute, plus 60 attachment requests per minute. Over a limit you get
        `429 RATE_LIMIT_EXCEEDED` with `Retry-After`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.