Mobile messaging: phone-book management, SMS campaign orchestration and delivery reporting.
openapi: 3.1.2
info:
title: SendPulse SMS API
description: >
The SendPulse SMS API enables global mobile messaging, contact management,
and campaign orchestration. It supports alphanumeric sender IDs, bulk
messaging, and advanced segmentation through variables.
version: 1.0.0
x-ai-description: >
Comprehensive SMS gateway for global mobile marketing and transactional
notifications. This API provides direct access to telecommunication routes
with localized routing intelligence and high-speed delivery capabilities.
license:
name: Apache 2.0
identifier: Apache-2.0
servers:
- url: https://api.sendpulse.com
paths:
/sms/numbers:
post:
summary: Add phone numbers to a mailing list
operationId: addSmsNumbers
tags:
- Contacts
x-ai-role: sms_marketing_specialist
x-ai-description: >
Imports a batch of phone numbers into a designated address book. This
is the baseline operation for building a mobile audience.
x-ai-reasoning-instructions:
- Verify the `addressBookId` exists before attempting the import.
- Ensure phone numbers are in international E.164 format (e.g., 380...).
x-ai-responding-instructions:
- Report the total number of successfully added contacts.
- Note if any numbers were skipped due to existing in the list.
x-ai-suggestions:
- >-
Use `addSmsNumbersWithVariables` if you have metadata like names or
dates.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- addressBookId
- phones
properties:
addressBookId:
type: integer
phones:
type: array
items:
type: string
responses:
'200':
description: Import result
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
counters:
type: object
properties:
added:
type: integer
exceptions:
type: integer
exists:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
put:
summary: Update variables for multiple phone numbers
operationId: updateSmsVariablesBatch
tags:
- Contacts
x-ai-role: sms_marketing_specialist
x-ai-description: >
Batch updates variable values for a set of phone numbers. Critical for
keeping contact data like 'Last Purchase' or 'Loyalty Points'
synchronized.
x-ai-reasoning-instructions:
- >-
Validate that the `variables` array contains correctly structured
objects (name, type, value).
x-ai-responding-instructions:
- Confirm the number of contacts updated.
x-ai-suggestions:
- Use this to refresh campaign-specific variables before a blast.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- addressBookId
- phones
- variables
properties:
addressBookId:
type: integer
phones:
type: array
items:
type: string
variables:
type: array
items:
type: object
required:
- name
- type
- value
properties:
name:
type: string
type:
type: string
enum:
- string
- number
- date
value:
oneOf:
- type: string
- type: number
responses:
'200':
description: Update result
content:
application/json:
schema:
type: array
items:
type: object
properties:
result:
type: boolean
counters:
type: object
properties:
updated:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
delete:
summary: Remove phone numbers from a mailing list
operationId: removeSmsNumbers
tags:
- Contacts
x-ai-role: compliance_officer
x-ai-description: >
Surgically removes specific mobile contacts from an address book.
Unlike the blacklist, this does not prevent future re-subscription.
x-ai-reasoning-instructions:
- Confirm the exact `addressBookId` to avoid cross-list deletions.
x-ai-responding-instructions:
- State clearly how many numbers were removed.
x-ai-suggestions:
- Use this for list hygiene (e.g., removing unengaged users).
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- addressBookId
- phones
properties:
addressBookId:
type: integer
phones:
type: array
items:
type: string
responses:
'200':
description: Deletion result
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
counters:
type: object
properties:
deleted:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/numbers/variables:
post:
summary: Add phone numbers with complex variables
operationId: addSmsNumbersWithVariables
tags:
- Contacts
x-ai-role: sms_marketing_specialist
x-ai-description: >
Advanced contact ingestion endpoint that maps specific variables to
each phone number in a single payload. Ideal for personalized
onboarding.
x-ai-reasoning-instructions:
- Note that `date` variable format must be `YYYY-MM-DD` (no time).
x-ai-responding-instructions:
- Confirm successful ingestion and variable mapping.
x-ai-suggestions:
- Structure your CRM export to match this schema for seamless sync.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- addressBookId
- phones
properties:
addressBookId:
type: integer
phones:
type: object
additionalProperties:
type: array
items:
type: array
items:
type: object
required:
- name
- type
- value
properties:
name:
type: string
type:
type: string
value:
type: string
responses:
'200':
description: Batch result
content:
application/json:
schema:
type: array
items:
type: object
properties:
result:
type: boolean
counters:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
/addressbooks/{id}/phone:
put:
summary: Change a phone number for a contact
operationId: updateContactPhone
tags:
- Contacts
parameters: []
x-ai-role: customer_engagement_specialist
x-ai-description: >
Maps an SMS identity to an existing email-based contact record. Enables
multi-channel communication (Email + SMS) for a single user entity.
x-ai-reasoning-instructions:
- Check if the contact exists by email first.
x-ai-responding-instructions:
- Confirm the user is now reachable via both Email and SMS.
x-ai-suggestions:
- >-
Check if the phone number is already associated with another email to
prevent duplication.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- phone
properties:
email:
type: string
phone:
type: string
responses:
'200':
description: Successfully updated
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: id
in: path
required: true
schema:
type: integer
/addressbooks/{id}/phones/variable:
post:
summary: Change variables for a single phone contact
operationId: updateSmsVariablesSingle
tags:
- Contacts
parameters: []
x-ai-role: customer_engagement_specialist
x-ai-description: >
Targeted update of metadata for a specific SMS contact within a list.
Useful for real-time updates (e.g., updating 'Last Visited' after a
store visit).
x-ai-reasoning-instructions:
- Strictly follow the `YYYY-MM-DD` format for date variables.
x-ai-responding-instructions:
- Confirm the variables have been updated for the contact.
x-ai-suggestions:
- Ensure the `id` corresponds to the correct address book.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- variables
properties:
phone:
type: string
variables:
type: array
items:
type: object
required:
- name
- value
properties:
name:
type: string
value:
oneOf:
- type: string
- type: number
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: id
in: path
required: true
schema:
type: integer
/sms/numbers/info/{addressBookId}/{phoneNumber}:
get:
summary: Get information for a specific phone number
operationId: getSmsNumberInfo
tags:
- Contacts
parameters: []
x-ai-role: customer_engagement_specialist
x-ai-description: >
Retrieves the profile of a mobile contact, including their current
variable values and the date they were added to the list.
x-ai-reasoning-instructions:
- Verify the status (e.g., 1 for active).
x-ai-responding-instructions:
- Summarize the contact's current metadata.
x-ai-suggestions:
- If status is inactive, investigate if the user was blacklisted.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Contact profile
content:
application/json:
schema:
type: array
items:
type: object
properties:
result:
type: boolean
data:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: addressBookId
in: path
required: true
schema:
type: integer
- name: phoneNumber
in: path
required: true
schema:
type: string
/sms/black_list:
post:
summary: Add phone numbers to the blacklist
operationId: addSmsBlacklist
tags:
- Compliance
x-ai-role: compliance_officer
x-ai-description: >
Global suppression for SMS. Prevents any future messages from being
sent to these numbers across all address books.
x-ai-reasoning-instructions:
- >-
Require a `description` to track the reason for blacklisting (e.g.,
'Spam complaint').
x-ai-responding-instructions:
- Confirm global suppression is active for these numbers.
x-ai-suggestions:
- Use this for 'Do Not Call' requests.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phones
- description
properties:
phones:
type: array
items:
type: string
description:
type: string
responses:
'200':
description: Blacklist result
content:
application/json:
schema:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
delete:
summary: Remove a phone number from the blacklist
operationId: removeSmsBlacklist
tags:
- Compliance
x-ai-role: compliance_officer
x-ai-description: >
Lifts the global suppression for specific numbers. Only perform this if
the user has explicitly re-consented.
x-ai-reasoning-instructions:
- Ensure audit logs reflect why the suppression was lifted.
x-ai-responding-instructions:
- Confirm the numbers are no longer suppressed.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phones
properties:
phones:
type: array
items:
type: string
responses:
'200':
description: Removal result
content:
application/json:
schema:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
get:
summary: Get a list of contacts in the blacklist
operationId: getSmsBlacklist
tags:
- Compliance
x-ai-role: compliance_officer
x-ai-description: |
Retrieves the master suppression list for auditing and external sync.
x-ai-responding-instructions:
- Present the current list of suppressed numbers.
x-ai-suggestions:
- Export this list for internal CRM synchronization.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Blacklist data
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/campaigns:
post:
summary: Create a campaign for a mailing list
operationId: createSmsCampaign
tags:
- Campaigns
x-ai-role: sms_marketing_specialist
x-ai-description: >
Triggers a bulk SMS broadcast to an entire address book. Supports
dynamic content, link tracking, and scheduled delivery.
x-ai-reasoning-instructions:
- 'Note: `sender` ID must be pre-registered (max 11 chars).'
- 'Use `emulate: true` to test logic without burning credits.'
- >-
Consider `use_dynamic_list: true` for scheduled campaigns to include
late subscribers.
x-ai-responding-instructions:
- Report the unique `campaign_id` generated.
- Remind the user that moderation may delay delivery by a few minutes.
x-ai-suggestions:
- Newsletter_Launch
- Flash_Sale_Promo
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- sender
- addressBookId
- body
properties:
sender:
type: string
maxLength: 11
addressBookId:
type: integer
body:
type: string
route:
type: object
description: e.g. {'UA':'national'}
date:
type: string
format: date-time
emulate:
type: boolean
default: false
use_dynamic_list:
type: boolean
default: false
stat_link_tracking:
type: boolean
default: false
stat_link_need_protocol:
type: boolean
default: false
responses:
'200':
description: Campaign created
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
campaign_id:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
delete:
summary: Delete a campaign
operationId: deleteSmsCampaign
tags:
- Campaigns
x-ai-role: sms_marketing_specialist
x-ai-description: >
Permanently deletes a campaign record. Only available for campaigns that
haven't started.
x-ai-reasoning-instructions:
- Check campaign status before attempting deletion.
x-ai-responding-instructions:
- Confirm deletion of the campaign.
x-ai-capabilities:
confirmation:
type: Required
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
responses:
'200':
description: Deleted successfully
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/send:
post:
summary: Create a campaign for a list of phone numbers
operationId: sendSmsToNumbers
tags:
- Campaigns
x-ai-role: sms_marketing_specialist
x-ai-description: >
Fast-track broadcast for ad-hoc lists not stored in an address book.
Perfect for one-off alerts or external CRM triggers.
x-ai-reasoning-instructions:
- Validate all numbers in the `phones` array are valid.
x-ai-responding-instructions:
- Report how many messages were successfully queued.
x-ai-suggestions:
- Use for 2FA codes or urgent system alerts.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- sender
- phones
- body
properties:
sender:
type: string
phones:
type: array
items:
type: string
body:
type: string
date:
type: string
route:
type: object
emulate:
type: boolean
stat_link_tracking:
type: boolean
stat_link_need_protocol:
type: boolean
responses:
'200':
description: Send result
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
campaign_id:
type: integer
counters:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/campaigns/list:
get:
summary: Get a list of campaigns by date
operationId: getSmsCampaigns
tags:
- Campaigns
x-ai-role: marketing_automation_specialist
x-ai-description: >
Retrieves campaign history within a specific time window. Useful for
building performance dashboards.
x-ai-reasoning-instructions:
- Use `dateFrom` and `dateTo` to avoid over-fetching.
x-ai-responding-instructions:
- Summarize the campaigns found in the requested period.
x-ai-suggestions:
- Track `company_price` to monitor spend trends.
x-ai-capabilities:
confirmation:
type: None
parameters:
- name: dateFrom
in: query
schema:
type: string
- name: dateTo
in: query
schema:
type: string
responses:
'200':
description: Campaign list
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/campaigns/info/{id}:
get:
summary: Get campaign information
operationId: getSmsCampaignInfo
tags:
- Campaigns
parameters: []
x-ai-role: sms_marketing_specialist
x-ai-description: >
Returns granular status for a campaign, including delivery breakdowns
per phone.
x-ai-reasoning-instructions:
- Examine `status` (2 for Delivered, 12 for Not Delivered).
x-ai-responding-instructions:
- Report delivery success rates and spend for this campaign.
x-ai-suggestions:
- Re-send to 'Not delivered' contacts if the failure was transient.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Campaign stats
content:
application/json:
schema:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: id
in: path
required: true
schema:
type: integer
/sms/campaigns/cancel/{id}:
put:
summary: Cancel a campaign before sending has started
operationId: cancelSmsCampaign
tags:
- Campaigns
parameters: []
x-ai-role: sms_marketing_specialist
x-ai-description: >
Stops a scheduled campaign from being sent. Emergency override for
erroneous scheduling.
x-ai-reasoning-instructions:
- Verify that sending has not already commenced.
x-ai-responding-instructions:
- Confirm the campaign has been successfully halted.
x-ai-suggestions:
- Check account balance to ensure credits are released.
x-ai-capabilities:
confirmation:
type: Required
responses:
'200':
description: Cancellation result
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: id
in: path
required: true
schema:
type: integer
/sms/campaigns/cost:
get:
summary: Calculate the cost of a campaign
operationId: calculateSmsCost
tags:
- Campaigns
x-ai-role: compliance_officer
x-ai-description: >
Estimates the total credit expenditure for a proposed campaign. Crucial
for budget planning before actual broadcast.
x-ai-reasoning-instructions:
- Note that parameters must be URL-encoded.
- Provide either `addressBookId` or `phones` array.
x-ai-responding-instructions:
- Report the estimated price and currency.
x-ai-suggestions:
- >-
Adjust the message `body` to fit within single SMS segments (160
chars) to save costs.
x-ai-capabilities:
confirmation:
type: None
parameters:
- name: addressBookId
in: query
schema:
type: integer
- name: phones
in: query
schema:
type: array
items:
type: string
- name: body
in: query
required: true
schema:
type: string
- name: sender
in: query
required: true
schema:
type: string
- name: route
in: query
schema:
type: object
responses:
'200':
description: Cost estimate
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: object
properties:
price:
type: number
currency:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
/sms/senders:
get:
summary: Get list of sender IDs
operationId: getSmsSenders
tags:
- Configuration
x-ai-role: sms_marketing_specialist
x-ai-description: >
Retrieves all approved Alphanumeric Sender IDs. Only IDs with status
'Active' (1) can be used for campaigns.
x-ai-reasoning-instructions:
- 'Check `status` (0: Moderation, 1: Active, 2: Rejected).'
x-ai-responding-instructions:
- Present the list of available sender identities.
x-ai-suggestions:
- If a sender is 'On moderation', wait before scheduling campaigns.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Sender ID list
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
sender:
type: string
country:
type: string
status:
type: integer
status_explain:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- apiKey: []
- oauth2: []
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: API Key
description: >
Static API Key authentication. A long-lived token generated manually in
the SendPulse account settings.
x-ai-description: >
Permanent authentication token. Ideal for simple integrations without
token refresh logic.
oauth2:
type: oauth2
description: OAuth 2.0 Client Credentials flow for temporary access tokens.
flows:
clientCredentials:
tokenUrl: https://api.sendpulse.com/oauth/access_token
scopes: {}
x-ai-description: >
Standard OAuth 2.0 flow using Client ID and Client Secret. Provides
temporary tokens (valid for 1 hour) for enhanced security.