# BulkSMS Message API

**Canonical:** https://apis.io/apis/bulksms/bulksms-message-api/  
**Provider:** BulkSMS — https://apis.io/providers/bulksms/  
**Base URL:** https://api.bulksms.com/v1  
**Documentation:** https://www.bulksms.com/developer/

BulkSMS Message API is one of 6 APIs that [BulkSMS](https://apis.io/providers/bulksms/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include Message. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

A message record represents an SMS that has been sent or received. To send messages, create a `SubmissionEntry` and submit it to the Send Messages Operation. You can retrieve sent and received messages in a number of ways. ### Retrieving messages by status Messages are assigned a status as they progress through their lifecycle. You can use the List Messages Operation to filter by various statuses. For the status values used to filter, see the `status.type` and `status.subtype` values of the `Message` object. You supply a value for the `filter` query parameter following this pattern `status.type==SENT`. Since more than one messages are normally returned, you can also paginate the result using the `sortOrder` and `limit` query parameters. Note that `limit` is not the only way to limit the number of records. The result will also be limited by the `filter.submissionDate` property. The default value for this property is `NOW() - 7 days`. Messages can also be retrieved by the webhook mechanism. See the [webhooks page](/developer/webhooks/) for more information. ### Sending and receiving messages The examples shown in this section are for a single message submission. If you need to send a single text message to one or more recipients you will need to create a `SubmissionEntry` object and submit it to the Send Messages Operation. For more advanced submission types, make use of the [Send Messages Operation](#tag/message/POST/messages) which supports batch sending (by submitting an array) and scheduling (via the `schedule-date` query parameter). The following fields can be set for a `SubmissionEntry`: - the `to` field is required and contains the phone number or group details - the `body` field is required and contains the message content - other fields like `from`, `routingGroup`, `encoding`, etc. are optional ### Body Templates When sending a message you can use template fields to customise the message text. *Field based templates* allow you to create a message with place-holders for custom fields. Fields are identified by a zero based index; the first field is `F0`, the second is `F1` and so on. For example, if you want to send a message "Welcome Jack, you owe $200.00", supply the body as `"Welcome {F0######}, you owe {F1######}"` and send `"fields": ["Jack", "$200.00"]` in the relevant `to` entry. The `#` characters specify the maximum length of the field. If you are sending to contacts in your phonebook, you can use *Phonebook based templates*. The template for the contact's first name is `{fn######}` and the surname is `{sn######}`. See the [Send Messages Operation](#tag/message/POST/messages) for detailed examples.

## Operations (5)

| Method | Path | Summary |
|---|---|---|
| GET | `/messages` | Retrieve Messages |
| POST | `/messages` | Send Messages |
| GET | `/messages/{id}` | Show Message |
| GET | `/messages/{id}/relatedReceivedMessages` | List Related Messages |
| GET | `/messages/send` | Send message by simple GET or POST |

## Machine-readable artifacts (7)

- **OpenAPI** — https://artifacts.apis.io/bulksms/openapi/bulksms-message-api-openapi.yml
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-submission-entry-schema.json
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-message-schema.json
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-webhook-entry-schema.json
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-profile-schema.json
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-transfer-entry-schema.json
- **JSONSchema** — https://artifacts.apis.io/bulksms/json-schema/bulksms-pre-sign-info-schema.json

## Other BulkSMS APIs (5)

- [BulkSMS Attachments API](https://apis.io/apis/bulksms/bulksms-attachments-api/)
- [BulkSMS Blocked Numbers API](https://apis.io/apis/bulksms/bulksms-blocked-numbers-api/)
- [BulkSMS Credits API](https://apis.io/apis/bulksms/bulksms-credits-api/)
- [BulkSMS Profile API](https://apis.io/apis/bulksms/bulksms-profile-api/)
- [BulkSMS Webhooks API](https://apis.io/apis/bulksms/bulksms-webhooks-api/)

## Tags

Message

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/bulksms/bulksms-message-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/bulksms/.