Cooper Email SMS API
SMS operations for the Cooper Email API.
Operations 9
POST
/api/v1/inboxes/{id}/owners/{ownerId}/phone/confirm
Confirm an owner phone with the texted code
#
SMS operations for the Cooper Email API.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/cooperemail-com:cooperemail-com-sms-api"
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.
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: 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