Postscript Messages API
Send promotional, transactional or conversational SMS and MMS to an existing subscriber, and read the resulting message request and sent message.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postscript Messages API
description: The Postscript Partner API (v2) lets partners and Shopify shops manage SMS subscribers, send custom events
into Flows, send transactional and conversational messages, read opt-in keywords, configure webhook subscriptions, and
run TCPA compliance operations (unsubscribe, redact). Harvested verbatim from the per-operation OpenAPI definitions published
on https://developers.postscript.io/reference.
version: '2.0'
contact:
name: Postscript Developer Support
email: developersupport@postscript.io
url: https://developers.postscript.io
termsOfService: https://postscript.io/api-terms-of-service
servers:
- url: https://api.postscript.io
security:
- sec0: []
tags:
- name: Messages
description: Send messages and read message requests and sent messages.
paths:
/api/v2/message_requests:
post:
summary: Send Message
description: Send a message to a subscriber.
operationId: create-message
parameters:
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used *only* by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- body
properties:
subscriber_id:
type: string
description: The ID of the subscriber to send the message to. Either `subscriber_id` or `phone` is **required**.
phone:
type: string
description: The phone number of the subscriber to send the message to. The subscriber must exist. Either
`phone` or `subscriber_id` is **required**. The phone number of the subscriber you want to send the message
to.
country:
type: string
description: ISO Alpha-2 country code, used to parse `phone` more accurately.
default: US
body:
type: string
description: The message body that you want to send to the subscriber.
category:
type: string
description: The category of message you are sending.
default: promotional
enum:
- promotional
- transactional
- conversational
scheduled_at:
type: string
description: 'ISO 8601 datetime to schedule delivery in the future. Default: `null` (deliver ASAP)'
format: date-time
media_url:
type: string
description: The URL of the media to send with the message. The media can be of type `gif`, `png`, and `jpeg`
and will be formatted correctly on the recipient's device. The media size limit is 1MB for supported file
types (JPEG, PNG, GIF) and 500KB for other types of accepted media. Please note that if you include a
media url with your message, then it gets sent as an MMS message, which has different costs and character
limits than SMS messages.
examples:
Request Example:
value:
phone: '15555555555'
body: Hello, world
category: promotional
media_url: https://example.com/great_pic.png
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value: "{\n \"body\": \"string\",\n \"category\": \"promotional\",\n \"created_at\": \"2019-08-24T14:15:22Z\"\
,\n \"id\": \"string\",\n \"phone\": \"string\",\n \"scheduled_at\": \"2019-08-24T14:15:22Z\",\n \"\
sent_message\": {\n \"body\": \"string\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"credits_used\"\
: 0,\n \"id\": \"string\",\n \"media_url\": \"string\",\n \"phone\": \"string\",\n \"shop_id\"\
: \"string\",\n \"subscriber_id\": \"string\"\n },\n \"status\": \"processing\",\n \"status_code\"\
: 0,\n \"subscriber_id\": \"string\",\n \"updated_at\": \"2019-08-24T14:15:22Z\"\n}"
schema:
type: object
properties:
body:
type: string
example: string
category:
type: string
example: promotional
created_at:
type: string
example: '2019-08-24T14:15:22Z'
id:
type: string
example: string
phone:
type: string
example: string
scheduled_at:
type: string
example: '2019-08-24T14:15:22Z'
sent_message:
type: object
properties:
body:
type: string
example: string
created_at:
type: string
example: '2019-08-24T14:15:22Z'
credits_used:
type: integer
example: 0
default: 0
id:
type: string
example: string
media_url:
type: string
example: string
phone:
type: string
example: string
shop_id:
type: string
example: string
subscriber_id:
type: string
example: string
status:
type: string
example: processing
status_code:
type: integer
example: 0
default: 0
subscriber_id:
type: string
example: string
updated_at:
type: string
example: '2019-08-24T14:15:22Z'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Messages
/api/v2/message_requests/{id}:
get:
summary: Get Message Request
description: ''
operationId: get-message-request
parameters:
- name: id
in: path
description: ID of the message request to look up.
schema:
type: string
required: true
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used *only* by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"body\": \"string\",\n \"category\": \"conversational\",\n \"created_at\": \"2019-08-24T14:15:22Z\"\
,\n \"id\": \"string\",\n \"phone\": \"string\",\n \"scheduled_at\": \"2019-08-24T14:15:22Z\",\n \"\
sent_message\": {\n \"body\": \"string\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"credits_used\"\
: 0,\n \"id\": \"string\",\n \"media_url\": \"string\",\n \"phone\": \"string\",\n \"shop_id\"\
: \"string\",\n \"subscriber_id\": \"string\"\n },\n \"status\": \"processing\",\n \"status_code\"\
: 0,\n \"subscriber_id\": \"string\",\n \"updated_at\": \"2019-08-24T14:15:22Z\"\n}"
schema:
type: object
properties:
body:
type: string
example: string
category:
type: string
example: conversational
created_at:
type: string
example: '2019-08-24T14:15:22Z'
id:
type: string
example: string
phone:
type: string
example: string
scheduled_at:
type: string
example: '2019-08-24T14:15:22Z'
sent_message:
type: object
properties:
body:
type: string
example: string
created_at:
type: string
example: '2019-08-24T14:15:22Z'
credits_used:
type: integer
example: 0
default: 0
id:
type: string
example: string
media_url:
type: string
example: string
phone:
type: string
example: string
shop_id:
type: string
example: string
subscriber_id:
type: string
example: string
status:
type: string
example: processing
status_code:
type: integer
example: 0
default: 0
subscriber_id:
type: string
example: string
updated_at:
type: string
example: '2019-08-24T14:15:22Z'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Messages
/api/v2/sent_messages/{id}:
get:
summary: Get Sent Message
description: ''
operationId: get-sent-message
parameters:
- name: id
in: path
description: ID of sent message to fetch.
schema:
type: string
required: true
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used *only* by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"body\": \"string\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"credits_used\": 0,\n\
\ \"id\": \"string\",\n \"media_url\": \"string\",\n \"phone\": \"string\",\n \"shop_id\": \"string\"\
,\n \"subscriber_id\": \"string\"\n}"
schema:
type: object
properties:
body:
type: string
example: string
created_at:
type: string
example: '2019-08-24T14:15:22Z'
credits_used:
type: integer
example: 0
default: 0
id:
type: string
example: string
media_url:
type: string
example: string
phone:
type: string
example: string
shop_id:
type: string
example: string
subscriber_id:
type: string
example: string
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"errors\": [\n {\n \"ctx\": {},\n \"log\": [\n \"string\"\n ],\n\
\ \"msg\": \"string\",\n \"type\": \"string\"\n }\n ]\n}"
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
ctx:
type: object
properties: {}
log:
type: array
items:
type: string
example: string
msg:
type: string
example: string
type:
type: string
example: string
deprecated: false
tags:
- Messages
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer