Cooper Email SMS API

SMS operations for the Cooper Email API.

GitHub OpenAPI

Operations 9

GET /api/v1/inboxes/{id}/phone-number Read the active phone number on an inbox #
POST /api/v1/inboxes/{id}/phone-number Provision a US local number for an inbox #
DELETE /api/v1/inboxes/{id}/phone-number Release the inbox phone number #
POST /api/v1/inboxes/{id}/sms Send an SMS from the inbox number #
GET /api/v1/phone-numbers List the account's active phone numbers #
GET /api/v1/phone-numbers/available Search US local numbers available to provision #
POST /api/v1/inboxes/{id}/owners/{ownerId}/phone Text a confirmation code to an owner phone #
POST /api/v1/inboxes/{id}/owners/{ownerId}/phone/confirm Confirm an owner phone with the texted code #
POST /api/v1/billing/sms-segments Set the 500-segment packs on the subscription #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cooperemail-com:cooperemail-com-sms-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cooperemail-com-sms-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Cooperemail Com SMS API
  version: 1.0.0
  contact:
    name: Avatar 8 LLC
    email: ops@avatar33.com
  license:
    name: Proprietary
    url: https://cooperemail.com/terms
  description: 'Operations tagged SMS across 2 of this provider''s published API definitions: cooperemail-com-openapi.json, cooperemail-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cooperemail.com
  description: This deployment
security:
- bearerAuth: []
tags:
- name: SMS
  description: SMS operations for the Cooper Email API.
paths:
  /api/v1/inboxes/{id}/phone-number:
    get:
      operationId: getInboxPhoneNumber
      tags:
      - SMS
      summary: Read the active phone number on an inbox
      description: Requires inbox_read. HTTP 404 not_found when COOPER_SMS is off, and in operators mode unless this account is an operator. HTTP 404 phone_number_not_found when the inbox has no active number. Another inbox on an inbox-scoped key is HTTP 404 inbox_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Active phone number. billing is omitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '404':
          description: not_found, phone_number_not_found, or inbox_not_found
    post:
      operationId: provisionPhoneNumber
      tags:
      - SMS
      summary: Provision a US local number for an inbox
      description: Requires inbox_update. A verified owner is required (HTTP 409 owner_required). One active number per inbox (HTTP 409 inbox_has_number). Free includes 0 numbers and returns HTTP 402 plan_limit_exceeded. Starter can hold up to 3. Pro includes 3 and caps at 25. A number past the included ones is $3/month and includes 100 segments. The same account can provision at most 3 numbers per 24 hours (HTTP 409 provision_limit) and waits 30 days before provisioning an E.164 it released (HTTP 409 number_cooldown). A paused inbox is HTTP 403 inbox_paused. With COOPER_SMS_BILLING=stripe, a billable number is added to the Stripe subscription (prorated) before Cooper buys it. If Stripe refuses, nothing is bought and the call returns HTTP 503 sms_billing_failed. billing.status is included or billed. Without that setting, billing.status is stub and this route does not call Stripe. Releasing later lowers the subscription quantity when billing is on. A grandfathered account is treated as Free for numbers unless it has a Starter or Pro subscription while SMS billing is on. Operators are not capped and are not billed. Idempotency-Key replays the same number. HTTP 404 not_found when SMS is off.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: ^[A-Za-z0-9._~-]+$
        description: 'Optional. 1 to 256 characters: letters, digits, and - . _ ~. The same key and the same request within 24 hours returns the stored message with HTTP 200, idempotent true, and Idempotent-Replayed: true, and does not send again. A different request is 409 idempotency_key_conflict. A second call while the first is still running is 409 idempotency_request_in_progress. An empty or invalid value is 400 invalid_idempotency_key. A definitive refusal removes the key. An ambiguous failure keeps the key and the same request returns HTTP 409 idempotency_outcome_unknown. When client_id is also set, client_id is checked first. Done keys expire after 24 hours. Unknown keys are kept for 7 days.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                area_code:
                  type: string
                  description: 3-digit US area code.
                phone_number:
                  type: string
                  description: E.164 US or Canada number.
              description: One of area_code or phone_number is required.
      responses:
        '200':
          description: Idempotency-Key replay of the same request. An ambiguous failure returns HTTP 409 idempotency_outcome_unknown.
        '201':
          description: Provisioned number, including billing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '402':
          description: plan_limit_exceeded. Includes upgrade_url.
        '403':
          description: inbox_paused
        '404':
          description: not_found or inbox_not_found
        '409':
          description: owner_required, inbox_has_number, provision_limit, number_cooldown, or phone_number_exists
        '503':
          description: sms_billing_failed. Nothing was purchased.
    delete:
      operationId: releasePhoneNumber
      tags:
      - SMS
      summary: Release the inbox phone number
      description: Requires inbox_update. Releases the number at the provider and marks it released. With COOPER_SMS_BILLING=stripe, the subscription quantity is lowered and Stripe prorates the charge. A failure to update Stripe is retried by the next provision or release, which recompute the quantity from the database. The same account waits 30 days before provisioning that E.164 again. HTTP 404 phone_number_not_found when there is no active number. HTTP 404 not_found when SMS is off.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Released number. inbox_id is null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '404':
          description: not_found, phone_number_not_found, or inbox_not_found
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/inboxes/{id}/sms:
    post:
      operationId: sendSms
      tags:
      - SMS
      summary: Send an SMS from the inbox number
      description: Requires message_send. POST returns HTTP 409 outbound_not_registered. HTTP 409 phone_number_not_found when the inbox has no active number. A recipient who replied STOP returns HTTP 409 recipient_opted_out until they reply START. The first message to a recipient adds an opt-out footer. HELP and STOP as the whole body return HTTP 400 reserved_keyword. SHAFT content returns HTTP 400 shaft_blocked. A URL shortener returns HTTP 400 short_link. The body, including the footer, must be 320 characters or fewer (HTTP 400 body_too_long). Outbound segments past the monthly allowance return HTTP 402 plan_limit_exceeded with resource sms_segments. Starter allowance is 100 segments per active number. Pro allowance is 1,500 plus 100 for each active number past the 3 included numbers. Purchased segment packs add 500 each when SMS billing is on. A paused inbox is HTTP 403 inbox_paused. The stored message has channel sms. A later Twilio status callback sets status to delivered, undelivered, or failed, and delivery_events carries the numeric error code. client_id and Idempotency-Key follow the send rules. HTTP 404 not_found when SMS is off.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: ^[A-Za-z0-9._~-]+$
        description: 'Optional. 1 to 256 characters: letters, digits, and - . _ ~. The same key and the same request within 24 hours returns the stored message with HTTP 200, idempotent true, and Idempotent-Replayed: true, and does not send again. A different request is 409 idempotency_key_conflict. A second call while the first is still running is 409 idempotency_request_in_progress. An empty or invalid value is 400 invalid_idempotency_key. A definitive refusal removes the key. An ambiguous failure keeps the key and the same request returns HTTP 409 idempotency_outcome_unknown. When client_id is also set, client_id is checked first. Done keys expire after 24 hours. Unknown keys are kept for 7 days.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  description: E.164 US or Canada recipient.
                text:
                  type: string
                client_id:
                  type: string
              required:
              - to
      responses:
        '200':
          description: client_id or Idempotency-Key replay. An ambiguous failure returns HTTP 409 idempotency_outcome_unknown.
        '201':
          description: Sent SMS message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: missing_body, reserved_keyword, shaft_blocked, short_link, body_too_long, or invalid_e164
        '402':
          description: plan_limit_exceeded for sms_segments
        '403':
          description: inbox_paused
        '404':
          description: not_found or inbox_not_found
        '409':
          description: outbound_not_registered, phone_number_not_found, or recipient_opted_out
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/phone-numbers:
    get:
      operationId: listPhoneNumbers
      tags:
      - SMS
      summary: List the account's active phone numbers
      description: Requires inbox_read. An inbox-scoped key lists only that inbox. Returns {object:"list", data:[phone numbers]}. HTTP 404 not_found when SMS is off.
      responses:
        '200':
          description: Active numbers
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    const: list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
                required:
                - object
                - data
        '404':
          description: not_found
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/phone-numbers/available:
    get:
      operationId: searchAvailablePhoneNumbers
      tags:
      - SMS
      summary: Search US local numbers available to provision
      description: Requires inbox_read. area_code is a 3-digit US area code (HTTP 400 invalid_area_code). contains is matched against the number. limit is 1 to 20 and defaults to 5 (HTTP 400 invalid_limit). Each row is {e164, number_type, capabilities}. HTTP 404 not_found when SMS is off.
      parameters:
      - name: area_code
        in: query
        schema:
          type: string
      - name: contains
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 20
      responses:
        '200':
          description: Inventory matches
        '400':
          description: invalid_area_code or invalid_limit
        '404':
          description: not_found
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/inboxes/{id}/owners/{ownerId}/phone:
    post:
      operationId: startOwnerPhone
      tags:
      - SMS
      summary: Text a confirmation code to an owner phone
      description: Requires owner_manage. The owner email must already be verified (HTTP 409 owner_not_verified). The number must have opted in at /sms-opt-in within the last 24 hours (HTTP 409 consent_required). Sends a code on Avatar 8 LLC's verified campaign from the toll-free number. Codes are limited to 5 per hour for a number. HTTP 404 owner_not_found for another inbox's owner. HTTP 404 not_found when SMS is off. The response does not include the code.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: ownerId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                e164:
                  type: string
                phone:
                  type: string
                  description: Same as e164. One of the two is required.
      responses:
        '201':
          description: Pending or already verified owner phone. The code is not returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerPhone'
        '404':
          description: not_found or owner_not_found
        '409':
          description: owner_not_verified or consent_required
        '429':
          description: rate_limited
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/inboxes/{id}/owners/{ownerId}/phone/confirm:
    post:
      operationId: confirmOwnerPhone
      tags:
      - SMS
      summary: Confirm an owner phone with the texted code
      description: Requires owner_manage. A matching code sets status to verified. A wrong code is HTTP 400 invalid_code. Too many attempts is HTTP 429. After confirmation, approval-needed and unread-over-24-hours alerts can text this phone. Those account notification texts are sent on Avatar 8 LLC's verified campaign, contain no action link, count toward the segment allowance, and do not fail the email when SMS fails. HTTP 404 not_found when SMS is off.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: ownerId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
              - code
      responses:
        '200':
          description: Verified owner phone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerPhone'
        '400':
          description: invalid_code or code_expired
        '404':
          description: not_found or owner_phone_not_found
        '429':
          description: rate_limited
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/billing/sms-segments:
    post:
      operationId: setSmsSegmentPacks
      tags:
      - SMS
      summary: Set the 500-segment packs on the subscription
      description: Requires billing_write on the parent account. A sub-account key is HTTP 403 workspace_billing_forbidden. HTTP 404 not_found when COOPER_SMS is off, and also when COOPER_SMS_BILLING is not stripe. Starter or Pro with a Stripe subscription is required (HTTP 402 plan_limit_exceeded otherwise). packs replaces the previous quantity, from 0 to 100. Each pack is $10/month and adds 500 outbound segments. An increase is invoiced immediately, and the pack count is saved only after Stripe confirms payment. A decrease is not credited. Packs already used stay locked until the Stripe period ends (HTTP 409 addon_below_usage). A past_due, unpaid, or incomplete subscription returns HTTP 402 subscription_not_current. A declined invoice is HTTP 402 addon_payment_failed and the quantity is not saved. The response is the new pack count, not a Checkout URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                packs:
                  type: integer
                  minimum: 0
                  maximum: 100
              required:
              - packs
      responses:
        '200':
          description: Pack quantity now on the subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsSegmentPacks'
        '400':
          description: packs outside 0 to 100
        '402':
          description: HTTP 402 plan_limit_exceeded when a Starter or Pro subscription is required. HTTP 402 subscription_not_current when the subscription is past_due, unpaid, or incomplete. HTTP 402 addon_payment_failed when the invoice is not paid.
        '403':
          description: workspace_billing_forbidden or permission_denied
        '404':
          description: not_found when SMS or SMS billing is off
        '409':
          description: HTTP 409 addon_below_usage when packs would drop below segments already sent.
        '503':
          description: sms_billing_failed
    servers:
    - url: https://cooperemail.com
      description: This deployment
components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        object:
          const: phone_number
        id:
          type: string
        account_id:
          type: string
        inbox_id:
          type:
          - string
          - 'null'
        e164:
          type: string
        provider:
          type: string
        provider_sid:
          type: string
        number_type:
          type: string
        capabilities:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - pending
          - active
          - released
        outbound:
          type: string
          description: disabled until a 10DLC brand is attached. enabled is required before POST /sms succeeds.
        brand_id:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        released_at:
          type:
          - string
          - 'null'
          format: date-time
        voice_greeting:
          type:
          - string
          - 'null'
          description: Spoken before a voicemail recording. Null uses the default greeting. Present when voice is on.
        voice_max_seconds:
          type:
          - integer
          - 'null'
          description: Recording cap from 15 to 300. Null uses 120 seconds, or 60 once the minute allowance is used. Present when voice is on.
        billing:
          $ref: '#/components/schemas/PhoneNumberBilling'
      required:
      - object
      - id
      - account_id
      - e164
      - provider
      - provider_sid
      - number_type
      - capabilities
      - status
      - outbound
      - created_at
    PhoneNumberBilling:
      type: object
      description: Present on provision and on an idempotent replay. included is $0 (Pro's first 3 numbers, or an operator). billed means COOPER_SMS_BILLING=stripe put this number on the subscription. stub means billing is off and stripe_price_id is the env price id or null. Cooper does not charge from a stub.
      properties:
        addon:
          const: cooper_phone_number_monthly
        status:
          type: string
          enum:
          - included
          - stub
          - billed
        monthly_cents:
          type: integer
        segments_included:
          type: integer
        stripe_price_id:
          type:
          - string
          - 'null'
      required:
      - addon
      - status
      - monthly_cents
      - segments_included
      - stripe_price_id
    SmsSegmentPacks:
      type: object
      properties:
        object:
          const: sms_segment_packs
        packs:
          type: integer
        previous_packs:
          type: integer
        segments_per_pack:
          type: integer
        extra_segments:
          type: integer
        monthly_cents:
          type: integer
        lookup_key:
          const: cooper_sms_500_monthly
      required:
      - object
      - packs
      - previous_packs
      - segments_per_pack
      - extra_segments
      - monthly_cents
      - lookup_key
    OwnerPhone:
      type: object
      properties:
        object:
          const: owner_phone
        id:
          type: string
        owner_id:
          type: string
        inbox_id:
          type: string
        e164:
          type: string
        status:
          type: string
          enum:
          - pending
          - verified
          - toll_free_verification_pending
        confirmed_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - object
      - id
      - owner_id
      - inbox_id
      - e164
      - status
    Message:
      type: object
      properties:
        id:
          type: string
        inbox_id:
          type: string
        thread_id:
          type: string
        folder:
          type: string
          enum:
          - inbox
          - archive
          - spam
          - trash
          description: Folder of this message's thread. inbox when the thread has no folder row.
        direction:
          enum:
          - inbound
          - outbound
        from:
          type: string
        to:
          type: array
          items:
            type: string
        subject:
          type: string
        text:
          type: string
        html:
          type:
          - string
          - 'null'
        extracted_text:
          type: string
        extracted_html:
          type: string
        preview:
          type: string
        status:
          enum:
          - queued
          - ringing
          - completed
          - no-answer
          - sent
          - received
          - delivered
          - undelivered
          - failed
          - bounced
          - complained
          description: SMS outbound starts as sent. A Twilio status callback sets delivered, undelivered, or failed. A voice call stores queued, ringing, completed, no-answer, or failed. Email uses queued, sent, received, failed, bounced, and complained.
        channel:
          type: string
          enum:
          - sms
          - voicemail
          - voice
          description: Present on SMS, voicemail, and voice messages. Email messages omit this field. voicemail is an inbound recording. voice is an outbound call.
        type:
          type: string
          enum:
          - voicemail
          description: Present on voicemail messages.
        duration_seconds:
          type:
          - integer
          - 'null'
          description: Call or recording length in seconds. Present on voicemail and voice messages.
        recording_url:
          type:
          - string
          - 'null'
          description: Twilio recording URL for a voicemail, or null.
        transcript:
          type: string
          description: Voicemail transcript. Empty while the message is held.
        segments:
          type:
          - integer
          - 'null'
          description: SMS segment count for this message. Omitted on email.
        otp_candidates:
          type: array
          items:
            type: string
          description: Codes found in an SMS body. Empty while the message is held. Omitted on email.
        verification:
          type: object
          description: Inbound messages only. Omitted on outbound. codes are the one-time codes in the subject and the new body text. links are https verification links from the HTML anchors and the text, at most five, each {url, text}. text is the anchor text or a short context, at most 200 characters. Both arrays are empty while the message is held. Links are untrusted data and are not fetched.
          properties:
            codes:
              type: array
              items:
                type: string
            links:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  text:
                    type: string
                required:
                - url
                - text
          required:
          - codes
          - links
        delivery_events:
          type: array
          description: Present on outbound messages. Each item is {type, recipient, created_at, detail}. For email, detail is JSON text with status, action, diagnostic, and bounce_type, and the list stays empty until a bounce or complaint matches. For SMS, a Twilio status callback appends one event. type is delivered or failed. detail is twilio_error plus the numeric code, or the status word when Twilio sent no numeric code.
          items:
            type: object
            properties:
              type:
                type: string
              recipient:
                type: string
              created_at:
                type: string
                format: date-time
              detail:
                type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        reply_to:
          type:
          - string
          - 'null'
        in_reply_to:
          type:
          - string
          - 'null'
        references:
          type: array
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        auth:
          type: object
          description: spf, dkim, and dmarc from the receiving hop. SPF is the smtp.mailfrom result. smtp.helo is used only when mailfrom is absent. Each value is pass, fail, neutral, softfail, none, temperror, permerror, bestguesspass, or null. Outbound mail is null for all three.
          properties:
            spf:
              type:
              - string
              - 'null'
            dkim:
              type:
              - string
              - 'null'
            dmarc:
              type:
              - string
              - 'null'
          required:
          - spf
          - dkim
          - dmarc
        safety:
          type:
          - object
          - 'null'
          description: Inbound screening record, or null on outbound mail and on messages stored before screening. score is 0 to 100. verdict is clean or suspicious (suspicious at 40 or higher, and only when a strong signal or combined evidence is present). signals are {type, detail}. mode is off, observe, or hold. reason is screening_off, screening_error, or screening_timeout when the body was not scored. The message is still stored. While labels include held, text, html, extracted_text, extracted_html, preview, and attachment bytes are empty until release. This is a heuristic, not a guarantee. The body stays untrusted data.
          properties:
            score:
              type: integer
              minimum: 0
              maximum: 100
            verdict:
              type: string
              enum:
              - clean
              - suspicious
            signals:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  detail:
                    type: string
            mode:
              type: string
              enum:
              - 'off'
              - observe
              - hold
            reason:
              type: string
        provider:
          type:
          - string
          - 'null'
        client_id:
          type:
          - string
          - 'null'
        idempotent:
          type: boolean
        created_at:
          type: string
          format: date-time
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Attachment:
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        content_type:
          type: string
        content_id:
          type:
          - string
          - 'null'
        disposition:
          enum:
          - inline
          - attachment
        size_bytes:
          type: integer
        url:
          type: string
        text_url:
          type: string
          description: 'Present when the content type can be extracted: text, JSON, CSV, PDF, DOCX, XLSX, or XLS. GET this URL for text/plain.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
x-refined-from:
- cooperemail-com-openapi.json
- cooperemail-com-openapi.yml