`POST` `https://mmsc.tsgglobal.world/mms/templates`
Creates a new MMS template. The template has placeholders so you can fill in per-customer information when you send.
### **Request body**
| Name | Type | Description |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------------- |
| `data.type` | string | Must be `"mms-template"` |
| `data.attributes.name` | string | **Required.** Template name |
| `data.attributes.body_template` | string | **Required.** Body text with `{placeholder}` syntax |
| `data.attributes.subject_template` | string | Optional. Subject line with `{placeholder}` syntax |
| `data.attributes.parts` | array | Optional. List of attachment parts (see below) |
| `data.attributes.parts[].kind` | string | **Required.** One of `"data-uri"`, `"uri"`, `"plain"`, `"embedded"` |
| `data.attributes.parts[].content_location` | string | Optional. Filename for the attachment |
| `data.attributes.parts[].uri` | string | Required for `"uri"` and `"data-uri"` kinds. The resource URI or RFC 2397 data URI |
| `data.attributes.parts[].body` | string | Required for `"plain"` kind |
| `data.attributes.parts[].content_type` | string | Optional. MIME type (default: `"text/plain"`) |
Placeholders use the pattern `{key}` where key matches `[a-zA-Z_][a-zA-Z0-9_]*`. Extracted placeholders are returned in the response. Attachments are copied to TSG-hosted storage at creation, so the `uri` values in the response differ from the ones you sent.
### Example with placeholders
#### Example of a request
Besides the text in `body_template` there are 2 parts: a data URI attachment (`kind: "data-uri"`) and an image referenced by URL (`kind: "uri"`).
```json
{
"data": {
"type": "mms-template",
"attributes": {
"name": "visit-thank-you",
"subject_template": "Hello {name}",
"body_template": "Dear {name}, welcome to {company}.",
"parts": [
{
"kind": "data-uri",
"content_location": "brochure.txt",
"uri": "data:text/plain,Hello%20Brochure"
},
{
"kind": "uri",
"content_location": "unnamed-1.png",
"uri": "https://www.tsgglobal.com/wp-content/uploads/2025/01/unnamed-1.png"
}
]
}
}
}
```
#### Example response
```json
{
"data": {
"attributes": {
"name": "visit-thank-you",
"parts": [
{
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/1-brochure.txt",
"content_type": "text/plain",
"content_location": "brochure.txt"
},
{
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/2-unnamed-1.png",
"content_type": "image/png",
"content_location": "unnamed-1.png"
}
],
"inserted_at": "2026-03-20T19:53:02.165449",
"updated_at": "2026-03-20T19:53:02.165449",
"placeholders": [
"name",
"company"
],
"body_template": "Dear {name}, welcome to {company}.",
"subject_template": "Hello {name}"
},
"id": "491aa990-1fbb-4058-8af0-c78049010d2f",
"type": "mms-template"
}
}
```
### Example without placeholders
A template does not have to contain placeholders. This example has none and a single image attachment provided by URL (`kind: "uri"`). **Note:** the attachment has to be publicly accessible.
#### Example of a request
```json
{
"data": {
"type": "mms-template",
"attributes": {
"name": "no-placeholder-example",
"subject_template": "New deals!",
"body_template": "Check our new deals!",
"parts": [
{
"kind": "uri",
"content_location": "unnamed-1.png",
"uri": "https://www.tsgglobal.com/wp-content/uploads/2025/01/unnamed-1.png"
}
]
}
}
}
```
#### Example response
```json
{
"data": {
"attributes": {
"name": "no-placeholder-example",
"parts": [
{
"uri": "https://content-mms.staging.smshub.world/templates/7c0e2d1a-5b3f-4c8e-9a21-0f6d4e8b2c17/attachments/1-unnamed-1.png",
"content_type": "image/png",
"content_location": "unnamed-1.png"
}
],
"inserted_at": "2026-03-20T19:55:10.412001",
"updated_at": "2026-03-20T19:55:10.412001",
"placeholders": [],
"body_template": "Check our new deals!",
"subject_template": "New deals!"
},
"id": "7c0e2d1a-5b3f-4c8e-9a21-0f6d4e8b2c17",
"type": "mms-template"
}
}
```
---
# Preview MMS Template
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/preview-mms-template
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/preview-mms-template.md
Last updated: 2026-03-23T16:23:29.551Z
For testing and debugging purposes, you can preview how the resulting MMS will look like without actually sending.
`POST` `https://mmsc.tsgglobal.world/mms/templates/:id/preview`
Renders a preview of the template with the given parameters without sending, where `:id` is the ID of the created template.
### **Request body**
| Name | Type | Description |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `data.type` | string | Must be `"mms-template-preview-req"` |
| `data.attributes.from` | string | **Required.** Sender number (E.164) |
| `data.attributes.to` | array of strings | **Required.** Recipient numbers (E.164) |
| `data.attributes.params` | object | **Required.** Key-value map of placeholder values. Must match all placeholders defined in the template |
### Example
#### Example request
```json
{
"data": {
"type": "mms-template-preview-req",
"attributes": {
"from": "18003004001",
"to": ["17818434375"],
"params": {
"name": "Jane",
"company": "TSG"
}
}
}
}
```
#### Example response
{
"data": {
"attributes": {
"metadata": {},
"from": "18003004001",
"parts": [
{
"metadata": {},
"uri": null,
"body": "Dear Jane, welcome to TSG.",
"kind": "plain",
"headers": {},
"content_type": "text/plain",
"content_location": null
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/1-brochure.txt",
"body": null,
"kind": "uri",
"headers": {},
"content_type": null,
"content_location": "brochure.txt"
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/2-unnamed-1.png",
"body": null,
"kind": "uri",
"headers": {},
"content_type": null,
"content_location": "unnamed-1.png"
}
],
"to": [
"17818434375"
],
"subject": "Hello Jane",
"request_delivery_reports": false
},
"id": "f67481a0-a532-4dda-b931-6973ce292558",
"type": "mms-forward-req"
}
}
### Example without placeholders
#### Example request
```json
{
"data": {
"type": "mms-template-preview-req",
"attributes": {
"from": "18003004001",
"to": ["17818434375"],
"params": {}
}
}
}
```
#### Example response
{
"data": {
"attributes": {
"metadata": {},
"from": "18003004001",
"parts": [
{
"metadata": {},
"uri": null,
"body": "New deals available!",
"kind": "plain",
"headers": {},
"content_type": "text/plain",
"content_location": null
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/2-unnamed-1.png",
"body": null,
"kind": "uri",
"headers": {},
"content_type": null,
"content_location": "unnamed-1.png"
}
],
"to": [
"17818434375"
],
"subject": "New deals!",
"request_delivery_reports": false
},
"id": "f67481a0-a532-4dda-b931-6973ce292558",
"type": "mms-forward-req"
}
}
---
# Send MMS Using Template
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/send-mms-using-template
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/send-mms-using-template.md
Last updated: 2026-03-23T16:24:38.997Z
POST /mms/templates/:id/send: send an MMS from a saved template by supplying recipients and placeholder values.
`POST` `https://mmsc.tsgglobal.world/mms/templates/:id/send`
Uses an existing template and sends the MMS.
### **Request body**
| Name | Type | Description |
| ------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `data.type` | string | Must be `"mms-template-send-req"` |
| `data.attributes.from` | string | **Required.** Sender number (E.164) |
| `data.attributes.to` | array of strings | **Required.** Recipient numbers (E.164) |
| `data.attributes.params` | object | **Required.** Key-value map of placeholder values. Must match all placeholders defined in the template |
| `data.attributes.transaction_id` | string | Optional. Client-provided transaction identifier |
| `data.attributes.request_delivery_reports` | boolean | Optional. Requesting DLR for the message to be sent to you. Defaults to false. Default: `false` |
| `data.attributes.metadata` | object | Optional. Additional metadata (default: `{}`) |
### Example
#### Example request
```json
{
"data": {
"type": "mms-template-send-req",
"attributes": {
"from": "18003004001",
"to": ["17818434375"],
"params": {
"name": "Jane",
"company": "TSG"
}
}
}
}
```
#### Example response
```json
{
"data": {
"attributes": {
"messages": [
{
"to": "17818434375",
"message_id": "035273d3-c20d-47ee-9d4c-7b732d36fbe0"
}
],
"from": "18003004001",
"parts": [
{
"kind": "plain",
"content_type": "text/plain",
"transfer_encoding": "identity",
"content_encoding": "identity"
},
{
"kind": "uri",
"transfer_encoding": "identity",
"content_encoding": "identity",
"content_location": "brochure.txt"
},
{
"kind": "uri",
"transfer_encoding": "identity",
"content_encoding": "identity",
"content_location": "unnamed-1.png"
}
],
"to": [
"17818434375"
],
"inserted_at": "2026-03-20T19:53:33.795259",
"subject": "Hello Jane",
"headers": {},
"expires_at": null,
"transaction_id": "e261793b-da9a-400f-9231-22e736af4d1c"
},
"id": "e13b4f90-5a39-405d-a729-0f2b9bca9d60",
"type": "mms-forward-res"
}
}
```
### Example without placeholders
### Example request
```json
{
"data": {
"type": "mms-template-send-req",
"attributes": {
"from": "18003004001",
"to": ["17818434375"],
"params": {}
}
}
}
```
### Example response
```json
{
"data": {
"attributes": {
"messages": [
{
"to": "17818434375",
"message_id": "035273d3-c20d-47ee-9d4c-7b732d36fbe0"
}
],
"from": "18003004001",
"parts": [
{
"kind": "plain",
"content_type": "text/plain",
"transfer_encoding": "identity",
"content_encoding": "identity"
},
{
"kind": "uri",
"transfer_encoding": "identity",
"content_encoding": "identity",
"content_location": "unnamed-1.png"
}
],
"to": [
"17818434375"
],
"inserted_at": "2026-03-20T19:53:33.795259",
"subject": "New deals!",
"headers": {},
"expires_at": null,
"transaction_id": "e261793b-da9a-400f-9231-22e736af4d1c"
},
"id": "e13b4f90-5a39-405d-a729-0f2b9bca9d60",
"type": "mms-forward-res"
}
}
```
---
# List MMS templates
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/list-mms-templates
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/list-mms-templates.md
Last updated: 2026-03-23T16:14:12.457Z
GET /mms/templates: list every MMS template on the account.
`GET` `https://mmsc.tsgglobal.world/mms/templates`
Returns all the templates for the account.
### Example response
```json
{
"data": [
{
"attributes": {
"name": "visit-thank-you",
"parts": [
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/1-brochure.txt",
"headers": {},
"content_type": "text/plain",
"content_location": "brochure.txt"
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/2-unnamed-1.png",
"headers": {},
"content_type": "image/png",
"content_location": "unnamed-1.png"
}
],
"inserted_at": "2026-03-20T19:53:02.165449",
"updated_at": "2026-03-20T19:53:02.165449",
"placeholders": [
"name",
"company"
],
"body_template": "Dear {name}, welcome to {company}.",
"subject_template": "Hello {name}"
},
"id": "491aa990-1fbb-4058-8af0-c78049010d2f",
"type": "mms-template"
},
{
"attributes": {
"name": "visit-thank-you",
"parts": [
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/185f821e-aac8-4296-88f4-035f155087f5/templates/1-brochure.txt",
"headers": {},
"content_type": "text/plain",
"content_location": "brochure.txt"
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/185f821e-aac8-4296-88f4-035f155087f5/templates/2-unnamed-1.png",
"headers": {},
"content_type": "image/png",
"content_location": "unnamed-1.png"
}
],
"inserted_at": "2026-03-20T17:08:33.315490",
"updated_at": "2026-03-20T17:08:33.315490",
"placeholders": [
"name",
"company"
],
"body_template": "Dear {name}, welcome to {company}.",
"subject_template": "Hello {name}"
},
"id": "185f821e-aac8-4296-88f4-035f155087f5",
"type": "mms-template"
},
{
"attributes": {
"name": "visit-thank-you",
"parts": [
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/0a4cfbcc-533f-4a87-aed7-e49bdfc20025/templates/1-brochure.txt",
"headers": {},
"content_type": "text/plain",
"content_location": "brochure.txt"
}
],
"inserted_at": "2026-03-20T16:53:12.572326",
"updated_at": "2026-03-20T16:53:12.572326",
"placeholders": [
"name",
"company"
],
"body_template": "Dear {name}, welcome to {company}.",
"subject_template": "Hello {name}"
},
"id": "0a4cfbcc-533f-4a87-aed7-e49bdfc20025",
"type": "mms-template"
}
]
}
```
---
# Get Single MMS template
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/get-single-mms-template
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/get-single-mms-template.md
Last updated: 2026-03-23T16:14:12.457Z
GET /mms/templates/:id: fetch one MMS template with its placeholders and attachments.
`GET` `https://mmsc.tsgglobal.world/mms/templates/:id`
Returns a single template by ID.
### Example response
```json
{
"data": {
"attributes": {
"name": "visit-thank-you",
"parts": [
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/1-brochure.txt",
"headers": {},
"content_type": "text/plain",
"content_location": "brochure.txt"
},
{
"metadata": {},
"uri": "https://content-mms.staging.smshub.world/templates/491aa990-1fbb-4058-8af0-c78049010d2f/attachments/2-unnamed-1.png",
"headers": {},
"content_type": "image/png",
"content_location": "unnamed-1.png"
}
],
"inserted_at": "2026-03-20T19:53:02.165449",
"updated_at": "2026-03-20T19:53:02.165449",
"placeholders": [
"name",
"company"
],
"body_template": "Dear {name}, welcome to {company}.",
"subject_template": "Hello {name}"
},
"id": "491aa990-1fbb-4058-8af0-c78049010d2f",
"type": "mms-template"
}
}
```
---
# Delete MMS Template
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/delete-mms-template
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/send-an-mms-message-using-templates/delete-mms-template.md
Last updated: 2026-03-23T16:25:55.606Z
DELETE /mms/templates/:id: remove an MMS template. Returns 204 No Content.
`DELETE` `https://mmsc.tsgglobal.world/mms/templates/:id`
Deletes a MMS template. Returns `204 No Content` on success.
---
# Receive an MMS Message
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/receive-an-mms-message
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/receive-an-mms-message.md
Last updated: 2026-03-23T16:25:55.606Z
Receive inbound MMS by HTTP webhook or MM4: routing address formats, request headers, payload, acknowledgement and retry rules.
## Overview
Get your message returned via SMTP or via a webhook URL that you provide.
## Routing Address
When requesting routing for your MMS messages, you may either specify an MM4 (SMTP) or HTTP endpoint.
It’s possible to provide Basic authentication details with the routing address:
HTTP Routing Address
`(http|https)://[:@][:][/*]`
**Examples**
* `http://example.com/inbound_messages`
* `http://username:password@example.com:8080/inbound_messages`
* `https://johndoe:secret@example.com:8080/messages/mms/tsg_inbound`
MM4 Routing Address
`mm4://[:@][:]`
**Examples**
* `mm4://example.com:2526`
* `mm4://johndoe:secret@example.com:2526`
## Webhook Format
All requests are made using the POST HTTP Verb to the specified endpoint.
Similar to the HTTP API, the webhook uses the very same format for delivering messages.
The request will include the following headers:
```http
Accept: application/json
Content-Type: application/json
User-Agent: Marshmallow/prod-x.y.z
X-Session-ID: aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa
```
**NOTE:** additional headers may be included that are not listed here.
## Webhook Response
When responding to the webhook request, respond with a 2xx status, more specifically:
* 200 OK
* 202 Accepted
* 204 No Content
Any of these statuses will be accepted as an acknowledgement of receive.
Otherwise the MMS system will assume delivery failed and will retry an additional 2 times within it’s current timeframe. If this fails once more, the message will be placed unto the retry and tried at a later time. The message will be retried a total of 20 times with an exponential backoff.
Once a message is received by the system and it’s routing is determined, it cannot be re-routed.
**Note:** All messages will keep their routing, changing a did’s routing will NOT affect messages already in-flight, this ensures that a message meant for an old endpoint will be delivered to that endpoint and nowhere else.
## Example Response
```
{
"data": [
{
"attributes": {
"expires_at": null,
"from": "14252437709",
"headers": {
"to": [
"+13462239287/TYPE=PLMN@mmsc.tsgglobal.world"
]
},
"inserted_at": "2022-04-06T21:50:06.316116",
"metadata": {},
"parts": [
{
"body": null,
"content_encoding": "identity",
"content_length": null,
"content_location": "476CC8E7CD30DBE0..unk",
"content_type": "application/smil",
"decoded": false,
"headers": {},
"id": "7a1ebff0-a8b7-4a24-b951-85b04ac6855a",
"kind": "uri",
"metadata": {},
"transfer_encoding": "identity",
"uri": "https://content.mms.smshub.world/prod/7160ce4c-0205-4e47-9eb7-3954991911c2/parts/476CC8E7CD30DBE0..unk"
},
{
"body": null,
"content_encoding": "identity",
"content_length": null,
"content_location": "image0000.JPG",
"content_type": "image/jpeg",
"decoded": false,
"headers": {},
"id": "7c2459ec-95b9-454d-8d9a-0293442b6459",
"kind": "uri",
"metadata": {},
"transfer_encoding": "identity",
"uri": "https://content.mms.smshub.world/prod/7160ce4c-0205-4e47-9eb7-3954991911c2/parts/photo.JPG"
}
],
"pool_name": null,
"request_delivery_reports": false,
"subject": "",
"to": [
"13462239287"
],
"transaction_id": "74def178-695b-4f04-9acd-efb3b0e7dab9",
"version": "2020-01-14"
},
"id": "61d55de8-8ccd-4bf3-8b51-848a8c21919b",
"type": "mms-forward-req"
}
]
}
```
---
# Receive DLRs
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/receive-dlrs
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/receive-dlrs.md
Last updated: 2023-12-05T09:20:57.619Z
MMS delivery reports: status codes, webhook headers and payload, and how retries work.
## Overview
You can receive DLR messages via SMTP or HTTP webhook on the same URL as regular messages. The original message is referenced in the `message_id` attribute. DLRs are only sent for messages submitted with `request_delivery_reports: true`.
## DLR status codes
| status code | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deferred | The handset has retrieved the MMS header, but has not downloaded the full message from the mobile network. The handset may still download the message at a later time. |
| Expired | The handset did not retrieve the message before the message expiration time. |
| Forwarded | The message has been sent successfully to the mobile network. |
| Indeterminate | The mobile network could not determine if the message was delivered correctly. |
| Rejected | The message has been rejected by the MMS gateway or mobile network. |
| Retrieved | The message was successfully delivered to the handset and the handset was configured to acknowledge the message with a delivery receipt. |
| Unrecognised | The handset of the mobile subscriber does not recognize the message content. |
## Webhook Format
All requests are made using the POST HTTP Verb to the specified endpoint.
The request will include the following headers:
```http
Accept: application/json
Content-Type: application/json
User-Agent: Marshmallow/prod-x.y.z
X-Session-ID: aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa
```
**NOTE:** additional headers may be included that are not listed here.
Example payload:
```json
{
"data": [
{
"id": "465542bf-6cf0-4023-8c72-cc9eede0ce01",
"type": "mms-delivery-report-res",
"attributes": {
"id": "465542bf-6cf0-4023-8c72-cc9eede0ce01",
"message_id": "9f3a72e9-7dc2-4741-96c7-ff2049b49b11",
"mm_status_code": "Retrieved",
"from": "12345678912",
"to": [
"+92345678912/TYPE=PLMN"
],
"transaction_id": "baf01b87-b987-4625-ae56-2ed506c41f7a"
}
}
]
}
```
## Webhook Response
You must respond with a 2xx status code to acknowledge the DLR message.
If you respond with a 5xx status code the MMS system will retry delivery later with an exponential backoff, similar to MMS delivery.
3xx and 4xx status codes will be considered as a permanent failure and we won't attempt re-delivery.
---
# SMTP
Source: https://support.tsgglobal.com/docs/api-reference/programmable-mms/smtp
Markdown: https://support.tsgglobal.com/docs/api-reference/programmable-mms/smtp.md
Last updated: 2023-04-13T17:42:48.000Z
Send MMS over MM4/SMTP: endpoints and ports, AUTH LOGIN/PLAIN with your SMPP system ID and API key, supported commands and an example exchange.
## Overview
It is possible to send MMS messages via SMTP using the MM4 services instead of the HTTP API.
## Authentication
MM4 servers support PLAIN and LOGIN AUTH mechanism.
Use the provided SMPP system\_id as the username, and the API Key as the password.
System IDs are normally 15 characters in length
## Available MM4 Endpoints
**TCP**
* `mmsc.tsgglobal.world:2525`
**TLS/SSL**
* `mmsc.tsgglobal.world:2465`
It is recommended to utilize the TLS port when capable. TLS supports versions 1.1 and 1.2.
## MM4 Commands
* `AUTH` - Mandatory
* `DATA` - Mandatory
* `EHLO` - Mandatory
* `HELO` - Available
* `MAIL` - Mandatory
* `NOOP` - Available, use to test if the connection is working
* `QUIT` - Available, optional, closing the connection also works
* `RCPT` - Mandatory
* `RSET` - Available
* `STARTTLS` - Disabled, use the TLS port instead
* `VRFY` - Unimplemented, and would be disabled
## MM4 Exchange Example
All lines must end with a `CRLF`. Some data has been omitted for brevity.
Note, arrows `> <` have been included in the example to denote origin of message.
* `>` Is a response from the server
* `<` Is input from the client
```
#
< NOOP
> 250 OK
< EHLO your_hostname
> MM4 server babble
< AUTH LOGIN
> 334 VXNlcm5hbWU6
< base64-encoded-system-id
> 334 UGFzc3dvcmQ6
< base64-encoded-api-key
> 235 Authentication successful
< MAIL FROM:
> 250 Sender OK
< RCPT TO:
> 250 Recipient OK
< DATA
> 354 enter mail, end with line containing only '.'
< your-mms-content-here
< .
> 250 queued as
< QUIT
> 221 BYE
```
Note the order of the commands:
* AUTH must be used before MAIL and RCPT.
* RCPT can only be used after a MAIL command.
* DATA can only be used after a MAIL and RCPT commands.
* QUIT, NOOP can be used at anytime (except while entering mail.)
Failure to do so will result in various errors
```
#
# AUTH before HELO
503 ERROR: send EHLO first
# RCPT or MAIL before EHLO
503 ERROR: send EHLO or HELO first
# RCPT before MAIL
503 ERROR: send MAIL first
# DATA before MAIL
503 ERROR: need MAIL command
# DATA before RCPT
503 ERROR: need RCPT command
```
---
# Phone Numbers
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers.md
Last updated: 2024-04-30T19:19:39.542Z
Get new numbers and manage existing numbers on your account.
---
# Search For New Available Numbers
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/search-for-new-available-numbers
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/search-for-new-available-numbers.md
Last updated: 2024-10-04T10:39:10.708Z
GraphQL numbers query: find local numbers by state and rate center or by NPANXX prefix, up to 100 at a time.
## Overview
Use this API to find a new local numbers that you can instantly use for messaging and voice. We allow users to search for numbers based on a contains field (NPANXX), or based on state + ratecenter. We allow you to search for consecutive numbers, and let you specify a quantity of numbers (up to 100 at a time).
These local numbers are instantly available for voice and SMS, or MMS (if you manually enable MMS on these numbers).
> **Info**
**Note:** this is for long-code numbers only, for toll-free numbers check this section:
[Toll-free phone numbers - search & ordering](https://support.tsgglobal.com/docs/api-reference/phone-numbers/toll-free-phone-numbers-search-and-ordering.md).
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Example Query Using State and Rate Center
```
query {
numbers(state: "MA", rateCenter:"BOSTON", quantity: 5, consecutive:false) {
numbers {
city
telephoneNumber
province
e911Allowed
mmsAllowed
}
}
}
```
## Example Response
```
{
"data": {
"numbers": {
"numbers": [
{
"city": "Chelsea",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "MA",
"telephoneNumber": "8572391650"
},
{
"city": "Chelsea",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "MA",
"telephoneNumber": "8572391651"
},
{
"city": "Chelsea",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "MA",
"telephoneNumber": "8572391653"
},
{
"city": "Chelsea",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "MA",
"telephoneNumber": "8572391654"
},
{
"city": "Chelsea",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "MA",
"telephoneNumber": "8572391655"
}
]
}
}
}
```
## Example Query Using Contains
```
query {
numbers(contains: "425", quantity: 5, consecutive:false) {
numbers {
city
telephoneNumber
province
e911Allowed
mmsAllowed
}
}
}
```
## Example Response
```
{
"data": {
"numbers": {
"numbers": [
{
"city": "Everett",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "WA",
"telephoneNumber": "4253864153"
},
{
"city": "Everett",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "WA",
"telephoneNumber": "4253864154"
},
{
"city": "Everett",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "WA",
"telephoneNumber": "4253864157"
},
{
"city": "Everett",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "WA",
"telephoneNumber": "4253864159"
},
{
"city": "Everett",
"e911Allowed": "Y",
"mmsAllowed": "Y",
"province": "WA",
"telephoneNumber": "4253864163"
}
]
}
}
}
```
---
# Add Number to Cart
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/add-number-to-cart
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/add-number-to-cart.md
Last updated: 2024-10-04T09:30:06.547Z
GraphQL numbersReserve mutation: reserve up to 100 searched numbers in your cart before checkout.
## Overview
Reserve up to 100 numbers at any time in your cart.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Example Mutation
```
mutation ReserveNumbers($numbers: [String]) {
numbersReserve(numbers: $numbers) {
reserved
reservedTotal
excluded
excludedTotal
requested
requestedTotal
}
}
```
### Query Variables
```
{
"numbers": ["8572144932", "8572144940"]
}
```
## Example Response
```
{
"data": {
"numbersReserve": {
"excluded": [],
"excludedTotal": 0,
"requested": [
"8572391650",
"8572391651"
],
"requestedTotal": 2,
"reserved": [
"8572391651",
"8572391650"
],
"reservedTotal": 2
}
}
}
```
---
# Get Reserved Numbers In Cart
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/get-reserved-numbers-in-cart
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/get-reserved-numbers-in-cart.md
Last updated: 2024-10-04T09:30:06.467Z
GraphQL reservedList query: see the numbers currently reserved in your cart.
## Overview
View all the numbers currently reserved in your cart.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Example Query
```
query {
reservedList {
numbers {
telephoneNumber
city
lata
}
}
}
```
## Example Response
```
{
"data": {
"reservedList": {
"numbers": [
{
"city": "BOSTON",
"lata": "128",
"telephoneNumber": "8572391650"
},
{
"city": "BOSTON",
"lata": "128",
"telephoneNumber": "8572391651"
}
]
}
}
}
```
---
# Remove Reserved Number From Cart
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/remove-reserved-number-from-cart
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/remove-reserved-number-from-cart.md
Last updated: 2024-10-04T09:30:06.487Z
GraphQL releaseReserved mutation: release reserved numbers you no longer want.
## Overview
Remove reserved numbers you no longer want from your cart.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Example Mutation
```
mutation CartRemove($numbers:[String]) {
releaseReserved(numbers:$numbers) {
excluded
excludedCount
releasedCount
totalCount
}
}
```
### Query Variables
```
{
"numbers": ["8572391651"]
}
```
## Example Response
```
{
"data": {
"releaseReserved": {
"excluded": [],
"excludedCount": 0,
"releasedCount": 1,
"totalCount": 1
}
}
}
```
---
# Checkout Numbers in Cart
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/checkout-numbers-in-cart
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/checkout-numbers-in-cart.md
Last updated: 2024-10-04T09:06:42.119Z
GraphQL numbersOrder mutation: purchase every number reserved in your cart and add it to your account.
## Overview
Checkout and purchase all of the currently reserved numbers in your cart.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Example Mutation
This function will add all the numbers currently reserved in your cart to your TSG Global account.
```
mutation OrderNumbers {
numbersOrder {
orderId
items {
tn
trunkGroup
tnNote
}
}
}
```
### Example Response
```
{
"data": {
"numbersOrder": {
"items": [
{
"tn": "8572391650",
"tnNote": null,
"trunkGroup": null
}
],
"orderId": 0
}
}
}
```
---
# Disconnect Number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/disconnect-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/disconnect-number.md
Last updated: 2024-10-04T09:30:06.547Z
GraphQL disconnectNumbers mutation: release a number from your account, subject to the 90-day holding requirement.
## Overview
Disconnect a number currently assigned to your account.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
Per your MSA, there is a 90 day number holding requirement. You can not specify a disconnect date, and the number will be disconnected at the earliest possible time (immediately if outside of the 90 day window).
## Example Mutation
```
# if a number is 12345600000
mutation {
disconnectNumbers(numbers: ["12345600000"]) {
internalId
orderId
orderName
requests {
disconnectAt
numbers
requestId
requestName
requestNotes
}
}
}
```
### Example Response
This is an example of a response - this one will disconnect right away (a disconnectAt timestamp is provided to provide some info for the user):
```
{
"data": {
"disconnectNumbers": {
"internalId": "999000053-ORD",
"orderId": "a0d0512f-7b61-4517-9e23-fd708344d52e",
"orderName": "Disconnect order",
"requests": [
{
"disconnectAt": "2021-09-21T13:52:36.664129Z",
"numbers": [
"15013929384"
],
"requestId": "2551e1c6-b99b-469a-b4b0-10439685f536",
"requestName": "Disconnect request",
"requestNotes": "Disconnect request will be executed right away"
}
]
}
}
}
```
Another response example - this one has a delayed disconnect request:
```
{
"data": {
"disconnectNumbers": {
"internalId": "999000030-ORD",
"orderId": "bf8a1a4d-9d4c-48e6-9feb-720bb3fc529e",
"orderName": "Disconnect order",
"requests": [
{
"disconnectAt": "2021-09-15T23:49:59.000000Z",
"numbers": [
"15013929405"
],
"requestId": "f9cd9320-a32f-43d6-bcf3-90652446e3a5",
"requestName": "Delayed disconnect request",
"requestNotes": "Disconnect request delayed due to too recent activation date (90 day disconnect rule)"
}
]
}
}
}
```
---
# Get Number Information
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/get-number-information
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/get-number-information.md
Last updated: 2024-10-01T21:11:17.085Z
Look up a number's SMS/MMS configuration and 10DLC status (GET /v5/dids/\), or its rate center, routing and activation data (GET /v1/did/lookup).
## Overview
Get basic information relating to a number, including rate center, state, sms enablement, and other data.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## SMS and MMS Configuration Method
## Returns information about the did (currently SMS and MMS configuration only).
`GET` `https://api-service.tsgglobal.world/v5/dids/`
Please ensure that your client processes only recognized properties from the response, as new properties may be added without prior notice. All added props will be documented here.
#### Path Parameters
| Name | Type | Description |
| ---------------------------------------- | ------ | ------------------------------ |
| number\* | string | The number that was looked up. |
### 200: OK
Each property below lists its possible values.
```json
{
"number": "13603556404",
"number_type": "long-code" | "short-code" | "toll-free",
"mms_enabled": true | false,
"mms_uri": "mm4://hooks.staging.tsgglobal.com",
"sms_enabled": true | false,
"campaign_id": null | "C12345",
"compliance_status": "non_compliant" | "pending" | "compliant",
"sms_status": "NONE" | "PENDING" | "ACTIVE" | "ERROR" | "DSBL-PND",
"use_case_type": "" | "p2p" | "a2p",
"nnid": "" | "12345" | null,
"sms_post_ver": "smpp" | "postv1" | "postv2" | "post3jam",
"sms_uri": null | "https://hooks.staging.tsgglobal.com",
"x_api_key_header": null | "" | "abcd1234",
"ten_dlc_registered": true | false,
"tmobile_ten_dlc_registered": true | false
}
```
Possible `sms_status` values:
* `N/A` or `NONE`: number not SMS enabled
* `PENDING`: number pending to be enabled
* `DSBL-PND`: number pending to be disabled
* `ACTIVE`: number SMS enabled
* `ERROR`: unable to SMS enable number, contact support
## Additional Data Method
## Lookup additional phone number information.
`GET` `https://api-service.tsgglobal.world/v1/did/lookup?did=<1NPANXXXXXX>`
If the `did` parameter is omitted all numbers on the matching account will be listed one per line.
#### Query Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------------------------------------- |
| did | string | `1NPANXXXXXX`, `+NPANXXXXXX`, `12022011234`, `+12022011234` |
### 200: OK
```csv
DID, ROUTING INFO, ACTIVATION DATE, LAST USED DATE, SEC USED, DID RATE, ORDER ID, RATE CENTER, STATE, TIER, PORTED, SMS ENABLED, SMS STATUS, SMS POST VERSION, SMS POST URL, PROVISIONING DATA, MAX CHANNELS
"17867469428","SIP/XXXX","2022-01-11 00:00:00","2022-05-01 00:00:01","0","0.0030000000","CUS9079-SMS","MIAMI","FL","0","N","t","ACTIVE","postv1","","ppm-did-billing-RFC2833-no+","2000"
```
---
# Manage Number for SMS & 10DLC
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc.md
Last updated: 2024-11-08T23:58:10.377Z
Enable or disable SMS on a number, attach a 10DLC campaign, and set the inbound SMS webhook.
---
# Enable SMS/10DLC on a Number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/enable-sms-10dlc-on-a-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/enable-sms-10dlc-on-a-number.md
Last updated: 2026-01-27T20:49:52.926Z
POST /v2/sms-enablement: enable SMS on a number, choose the inbound webhook format, and assign a 10DLC campaign.
## Overview
This method allows you to enable SMS on (almost) any number with TSG Global.
> **Success**
Numbers that are searched and ordered in your cart are already SMS enabled, and you do not need to perform this function to make them SMS enabled.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Enable SMS on a phone number.
`POST` `https://api-service.tsgglobal.world/v2/sms-enablement`
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| did\* | String | The DID you would like to modify" |
| action\* | String | \[add \| update] (use update if you need to ammend information for already SMS-enabled number - eg. change webhook url or add campaign id) |
| use\_case\_type | String | \[a2p \| p2p \| account\_default] - p2p can be used only if you have p2p use-case approved |
| p2p\_nnid | String | to be used with use\_case\_type p2p and approved nnid for p2p traffic |
| mms\_enable | String | \[true \| false] - if not set, account default value will be used |
| mms\_routing | String | http, https, mm4, mm4s url to deliver inbound mms to - if not set, account default value will be used |
| webhook\_url | String | http or https SMS webhook url if you want inbound SMS delivered via webhook (leave blank for SMPP or account default value) |
| webhook\_type | String | \[smpp, postv1, postv2, post3jam] - leave blank for account default settings. It determines inbound message format. postv2 recommended for http(s) deliveries (if webhook url set) |
| x\_api\_key\_header | String | This value will be passed as x-api-key header in the webhook http call. Can be used to secure your webhook API. (should not be provided if webhook\_type is smpp) |
| campaign\_id | String | If the number is needs to be 10DLC registered and assigned to an active campaign, the campaign id should be provided here to complete 10DLC provisioning. Note: sole proprietor campaigns only allow 1 number at a time. |
| campaign\_sub\_id | String | In case your campaign is associated with the sub id please provide one. Otherwise, do not provide this parameter. |
| skip\_number\_validation | String | Setting this optional prop to "true" allows you to provision number that you provided LOA for and you got confirmation from TSG team that it was accepted. Using this prop without TSG confirmation will have no effect - your request will be stale. |
> **Info**
Please be aware that this API endpoint has strict parameter parsing. In case an unknown or invalid parameter is provided in the request body, the request will be rejected with an error.
### 200: OK Success
```javascript
Success
```
---
# Disable SMS on a Number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/disable-sms-on-a-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/disable-sms-on-a-number.md
Last updated: 2026-01-27T20:49:52.926Z
Remove SMS capability from a phone number with the sms-enablement endpoint (action: delete).
## Overview
This method allows you to remove SMS functionality from a number.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Disable SMS on a DID.
`POST` `https://api-service.tsgglobal.world/v2/sms-enablement`
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------ | ------------------------------- |
| did\* | String | The DID you want to sms disable |
| action\* | String | `delete` |
> **Info**
Please be aware that this API endpoint has strict parameter parsing. In case an unknown or invalid parameter is provided in the request body, the request will be rejected with an error.
### 200: OK Success
```javascript
Success
```
## Example CURL
```bash
curl https://api-service.tsgglobal.world/v2/sms-enablement -XPOST -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"did": "12003004000",
"action": "delete"
}'
```
---
# Update inbound SMS webhook/URI
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/update-inbound-sms-webhook-uri
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-sms-and-10dlc/update-inbound-sms-webhook-uri.md
Last updated: 2026-01-27T20:50:27.289Z
Set or change the inbound SMS webhook URL, format and shared secret for a phone number, or switch the number back to SMPP delivery.
## Overview
This method allows you to update your inbound messaging webhook/URI for a phone number.
> **Danger**
If you are an HTTP API customer and do not use SMPP, `webhook_url` must be a fully qualified URL, for example `https://api.example.com/inbound-sms`.\
\
Leaving `webhook_url` blank or omitting it converts the number from HTTP POST delivery to SMPP delivery.\
\
Make sure you have SMPP credentials set up and tested before converting numbers to SMPP, otherwise inbound messages can be lost.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Update per-DID configuration. Currently only the SMS webhook URL can be changed with this endpoint.
`POST` `https://api-service.tsgglobal.world/v1/sms/webhook`
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| webhook\_url | String | e.g. |
| did\* | String | DID you want to set/update SMS webhook endpoint for |
| webhook\_type | String | postv2 (default) \| postv1 \| post3jam \| smpp |
| x\_api\_key\_header | String | This value will be passed as x-api-key header in the webhook http call. Can be used to secure your webhook API. (should not be provided if webhook\_type is smpp) |
### 200: OK
```javascript
Success
```
## Example CURL
```bash
curl -n https://api-service.tsgglobal.world/v1/sms/webhook -XPOST -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"webhook_url": "https://example.com/webhook",
"did": "12003004000"
}'
```
---
# Manage Number for MMS
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms.md
Last updated: 2024-12-06T17:09:24.404Z
Enable or disable MMS on a number and set where inbound MMS is delivered.
---
# Enable MMS on a Number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/enable-mms-on-a-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/enable-mms-on-a-number.md
Last updated: 2024-12-06T17:09:24.398Z
POST /v2/dids/\/mms/enable: turn on MMS for an SMS-enabled number and set its inbound HTTP(S) or MM4 URI.
## Overview
This method allows you to enable MMS on a phone number.
> **Danger**
As a prerequisite to use MMS, the number you are enabling must already be SMS enabled, and your account must have MMS enabled. Contact if you have any concerns.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
`POST` `https://api-service.tsgglobal.world/v2/dids//mms/enable`
#### Path Parameters
| Name | Type | Description |
| ---------------------------------------- | ------ | --------------------------------------- |
| number\* | String | The phone number you want to MMS enable |
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| uri\* | String | A URI pointing to the destination at which you want to receive the messages. Can either be HTTP(S) or an MMS server. |
### 200: OK
```javascript
{
"mms_enabled": true,
"mms_uri": "http://mms.example.com",
"number": "12342341234",
"sms_enabled": true,
"sms_uri": null # null means SMPP
}
```
---
# Disable MMS on a Number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/disable-mms-on-a-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/disable-mms-on-a-number.md
Last updated: 2022-12-19T09:44:57.000Z
Turn off MMS on a phone number. The number keeps its SMS configuration.
## Overview
This method allows you to disable MMS on a phone number.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Disable MMS on a phone number.
`POST` `https://api-service.tsgglobal.world/v2/dids//mms/disable`
#### Path Parameters
| Name | Type | Description |
| ---------------------------------------- | ------ | ------------------------------------- |
| number\* | string | The phone number you want to disable. |
The response is the number's updated SMS/MMS configuration, in the same shape as [Enable MMS on a Number](https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/enable-mms-on-a-number.md), with `mms_enabled` set to `false`.
### 200: OK
```json
{
"mms_enabled": false,
"mms_uri": null,
"number": "12342341234",
"sms_enabled": true,
"sms_uri": null
}
```
## Example CURL
```bash
curl https://api-service.tsgglobal.world/v2/dids/12342341234/mms/disable -XPOST -H "Authorization: Bearer "
```
---
# Update inbound MMS webhook/URI
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/update-inbound-mms-webhook-uri
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/update-inbound-mms-webhook-uri.md
Last updated: 2022-12-19T10:21:15.000Z
Change the HTTP(S) or MM4 destination that receives inbound MMS for a phone number. Uses the same endpoint as Enable MMS.
## Overview
Update the webhook/URI for inbound MMS messages. This uses the same endpoint as [Enable MMS on a Number](https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-mms/enable-mms-on-a-number.md): calling it on a number that already has MMS enabled replaces the inbound URI.
> **Danger**
As a prerequisite to use MMS, the number must already be SMS enabled, and your account must have MMS enabled. Contact if you have any concerns.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
To change where inbound MMS is delivered, call the endpoint below with the new `uri`.
`POST` `https://api-service.tsgglobal.world/v2/dids//mms/enable`
#### Path Parameters
| Name | Type | Description |
| ---------------------------------------- | ------ | --------------------------------------------------------- |
| number\* | String | The phone number whose inbound MMS URI you want to update |
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| uri\* | String | A URI pointing to the destination at which you want to receive the messages. Can either be HTTP(S) or an MMS server. |
### 200: OK
```json
{
"mms_enabled": true,
"mms_uri": "http://mms.example.com",
"number": "12342341234",
"sms_enabled": true,
"sms_uri": null
}
```
`sms_uri` of `null` means inbound SMS for the number is delivered over SMPP.
---
# Manage Number for Voice
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice.md
Last updated: 2024-04-30T19:19:39.067Z
List, add, update and delete the voice destination priorities (VoIP gateways or PSTN numbers) for your phone numbers.
---
# List Destination Priority
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/list-destination-priority
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/list-destination-priority.md
Last updated: 2023-02-15T12:25:01.000Z
List the voice destination priorities configured for your phone numbers (GET /v1/did/priority/lookup, CSV response).
## Overview
This method lets you list the voice destination priority for phone numbers.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## List destination priorities associated with your phone numbers.
`GET` `https://api-service.tsgglobal.world/v1/did/priority/lookup`
### 200: OK
```csv
DID,ROUTING INFO,PRIORITY,CALL TYPE
13603556939,SIP/+13603556939@SIP/13603556939@209.119.133.123,1,1
13603556939,SIP/13603556939@SIP/13603556939@209.119.133.123,2,1
13603556404,SIP/13603556404@8.30.173.27,1,1
13603556404,SIP/13603556404@8.36.70.27,2,1
```
---
# Add Destination Priority
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/add-destination-priority
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/add-destination-priority.md
Last updated: 2022-12-19T10:44:11.000Z
Add a voice destination (VoIP gateway or PSTN number) at priority 1–3 for a phone number.
## Overview
This method lets you add a voice destination priority for a phone number.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Add a destination priority associated with a phone number.
`POST` `https://api-service.tsgglobal.world/v1/did/priority`
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------------------------------------------- |
| did\* | String | The phone number (e.g. 12022011234) |
| priority\* | String | 1-3 in order of preferred priority. |
| destination\* | String | `192.168.1.1` (for VOIP), `16352321233` (for PSTN) |
| call\_type\* | String | `VOIP`, `PSTN` |
| call\_option | String | `WP`, `NP` |
For VOIP Call Type you need to enter just the IP Address of the Gateway and we will format the rest of the destination. For PSTN Call Type you need to just enter the PSTN Destination in E.164 format, with or without the leading plus.
`call_type` must be exactly one of `VOIP` (VoIP destination) or `PSTN` (PSTN destination). This value is case sensitive.
`call_option`: `NP` = DID sent to the gateway without a plus, `WP` = DID sent to the gateway with a plus. This value is case sensitive.
### Example POST (PSTN)
```bash
curl -n https://api-service.tsgglobal.world/v1/did/priority -XPOST -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"did": "12003004000",
"destination": "16352321233",
"priority": 2,
"call_type": "PSTN",
"call_option": "NP"
}'
```
### Example POST (VOIP)
```bash
curl -n https://api-service.tsgglobal.world/v1/did/priority -XPOST -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"did": "12003004000",
"destination": "192.168.1.1",
"priority": 3,
"call_type": "VOIP",
"call_option": "NP"
}'
```
## **Error Codes**
* `-1000` Invalid or Blank API Key
* `-1001` Invalid or Blank Call Option
* `-1003` Invalid or No DID Provided
* `-1004` Invalid or No Priority Provided
* `-1005` Invalid or No Destination Provided
* `-1006` Invalid or No Call Type Provided
* `-1007` Priority Already Exists Use Another Priority
* `-1008-V` Priority Added to Database as VoIP Destination
* `-1008-P` Priority Added to Database as PSTN Destination
* `-1010` Unknown Error Please Contact TSG Support with URL String for Review
---
# Update Destination Priority
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/update-destination-priority
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/update-destination-priority.md
Last updated: 2022-12-19T10:43:46.000Z
Change an existing voice destination priority for a phone number, optionally overriding the dialed number (DNIS) sent to your switch.
## Overview
This method allows you to update existing destination priorities for phone numbers.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Update a destination priority associated with a phone number.
`PATCH` `https://api-service.tsgglobal.world/v1/did/priority`
#### Request Body
| Name | Type | Description |
| ---------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| did\* | String | The phone number (e.g. 12022011234) |
| priority\* | String | 1-3 in order of preferred priority. |
| destination\* | String | `192.168.1.1` (for VOIP), `16352321233` (for PSTN) |
| call\_type\* | String | `VOIP`, `PSTN` |
| call\_option\* | String | `WP`, `NP` |
| dnis | String | Number for TSG to send to your switch as the Dialed Number ID, e.g. `DID == 13605551212` but you want TSG to send you `3605551212` or `14085551212` instead of the DID number |
For VOIP Call Type you need to enter just the IP Address of the Gateway and we will format the rest of the destination. For PSTN Call Type you need to just enter the PSTN Destination in E.164 format, with or without the leading plus.
`call_type` must be exactly one of `VOIP` (VoIP destination) or `PSTN` (PSTN destination). This value is case sensitive.
`call_option`: `NP` = DID sent to the gateway without a plus, `WP` = DID sent to the gateway with a plus. This value is case sensitive.
### Example PATCH
```bash
curl -n https://api-service.tsgglobal.world/v1/did/priority -XPATCH -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"did": "12003004000",
"destination": "16352321233",
"priority": 2,
"call_type": "PSTN",
"call_option": "NP"
}'
```
## **Error Codes**
* `-1000` Invalid or Blank API Key
* `-1001` Invalid or Blank Call Option
* `-1003` Invalid or No DID Provided
* `-1004` Invalid or No Priority Provided
* `-1005` Invalid or No Destination Provided
* `-1006` Invalid or No Call Type Provided
* `-1007` Priority Already Exists Use Another Priority
* `-1008-V` Priority Added to Database as VoIP Destination
* `-1008-P` Priority Added to Database as PSTN Destination
* `-1010` Unknown Error Please Contact TSG Support with URL String for Review
---
# Delete Destination Priority
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/delete-destination-priority
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/manage-number-for-voice/delete-destination-priority.md
Last updated: 2022-12-19T10:43:11.000Z
Remove a voice destination priority (2 or 3) from a phone number. Priority 1 cannot be deleted through the API.
## Overview
This method allows you to remove destination priorities for phone numbers.
## Authentication
> **Info**
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \"
## Method
## Delete a destination priority associated with a phone number.
`DELETE` `https://api-service.tsgglobal.world/v1/did/priority`
#### Request Body
| Name | Type | Description |
| ------------------------------------------ | ------ | ----------------------------------- |
| did\* | String | The phone number (e.g. 12022011234) |
| priority\* | String | 1-3 in order of preferred priority. |
## Example DELETE
```bash
curl -n https://api-service.tsgglobal.world/v1/did/priority -XDELETE -H "Authorization: Bearer " \
-H "Content-Type: application/json" -d '{
"did": "12003004000",
"priority": 2
}'
```
## **Error Codes**
* `-1000` Invalid or Blank API Key
* `-1003` Invalid or No DID Provided
* `-1004` Invalid or No Priority Provided
* `-1007` Priority Does NOT Exist, Delete an already created priority.
* `-1008` Deleted Priority from Routing.
* `-1010` Can not Delete Priority 1, Please Submit a DID cancel request.
---
# Protect your phone number
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/protect-your-phone-number
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/protect-your-phone-number.md
Last updated: 2023-03-30T08:46:30.000Z
Have you ever experienced the discomfort and frustration of your phone number is changed to a different SMS carrier without your consent?
We offer a solution for that. With TSG you can protect messaging portion of your number from being SMS enabled with another SMS vendor in just a few clicks and get notified every time an attempt is made.\
If you would like to Text Protect your numbers, change the webhook notifications URL or remove protection for some of the numbers please reach out to and we will be happy to assist.\
\
For webhook API specification please check the [next page](https://support.tsgglobal.com/docs/api-reference/phone-numbers/protect-your-phone-number/textprotect-webhook.md).
---
# TextProtect Webhook
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/protect-your-phone-number/textprotect-webhook
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/protect-your-phone-number/textprotect-webhook.md
Last updated: 2023-03-30T08:23:02.000Z
Payload TSG posts to your URL whenever TextProtect blocks an attempt to move your number to another SMS provider, retried for 72 hours.
To receive notification on every unauthorized attempt for changing your number messaging provider please provide an URL that exposes HTTP POST endpoint and accepts the body model like in the example below.
```json
{
"number": "1200300400",
"sms_account": "TSG100000",
"requester_nnid": "123456",
"requester": "carrier",
"timestamp": "2023-03-30T08:14:19.688501",
"description": "Request rejected by TextProtect"
}
```
Please respond with 200 OK on success, otherwise, our webhook will retry for the next 72 hours with exponential backoff. If we are unable to deliver the webhook after 72 hours the retry will stop.
---
# Toll-free phone numbers - search & ordering
Source: https://support.tsgglobal.com/docs/api-reference/phone-numbers/toll-free-phone-numbers-search-and-ordering
Markdown: https://support.tsgglobal.com/docs/api-reference/phone-numbers/toll-free-phone-numbers-search-and-ordering.md
Last updated: 2024-10-04T10:35:50.869Z
Shows how to search and order toll-free numbers.
Use this API to find new toll-free numbers. We allow users to search for numbers based on a contains field. We allow you to search for consecutive numbers, and let you specify a quantity of numbers (up to 10 at a time).
To use Toll-free numbers there's only 2 steps - search and order, no reservation or checkout necessary.
## Authentication
> **Info**
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Search for toll-free numbers
To search for numbers use the `searchPhoneNumbersQuery` GraphQL query, it'll return a list of numbers you can order. The numbers aren't reserved, so maybe they won't be available until you decide to order, in that case, just search for new numbers.
```graphql
query searchPhoneNumbersQuery(
$contains: String
$quantity: Int
$consecutive: Boolean
) {
tollfreeNumbers(
contains: $contains
quantity: $quantity
consecutive: $consecutive
) {
numbers
}
}
```
### Example variables
```json
{
"contains":"888xxxxxxx",
"quantity":2,
"consecutive":false
}
```
### Example response
```json
{
"data": {
"tollfreeNumbers": {
"numbers": [
"18886834580",
"18886834690"
]
}
}
}
```
## Order toll-free numbers
To order toll-free numbers, pass the numbers from the previous call and set smsEnable to true or false, depending if you want to enable the numbers for SMS.
It usually takes about 10 minutes for voice service activation. For SMS you need to submit a Verified Sender form for ordered numbers.
```graphql
mutation orderTollfreeNumbersMutation(
$numbers: [String]
$smsEnable: Boolean
) {
orderTollfreeNumbers(numbers: $numbers, smsEnable: $smsEnable) {
numbers
orderId
}
}
```
### Example variables
```json
{
"numbers": ["18886830411"],
"smsEnable":true
}
```
### Example response
```json
{
"data": {
"orderTollfreeNumbers": {
"numbers": ["18886830411"],
"orderId":"999000261-ORD"
}
}
}
```
> **Info**
**Remember:** After ordering toll-free numbers, you should register a campaign for them using the Toll-Free Verified Sender Form, you can find the [form here](https://customer-portal.tsgglobal.com/tf-verification-form).
More info on campaign registration can be [here](https://support.tsgglobal.com/hc/en-us/articles/5872363711387-New-Toll-Free-SMS-MMS-Verified-Sender-Requirements).
## Disconnecting toll-free numbers
To disconnect a toll-free number, check the following section.
[Disconnect Number](https://support.tsgglobal.com/docs/api-reference/phone-numbers/disconnect-number.md)
---
# Reports
Source: https://support.tsgglobal.com/docs/api-reference/reports
Markdown: https://support.tsgglobal.com/docs/api-reference/reports.md
Last updated: 2024-03-21T15:56:06.115Z
Call and message detail records (CDRs) through the GraphQL API.
---
# CDR Records
Source: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records
Markdown: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records.md
Last updated: 2024-03-21T15:56:06.115Z
Count and list CDRs for a period, page through them with cursors, and export them as CSV.
---
# Get Count of CDR Records
Source: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records/get-count-of-cdr-records
Markdown: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records/get-count-of-cdr-records.md
Last updated: 2024-03-21T15:54:53.035Z
How to count CDR records for a period using the cdrRecords GraphQL query.
## Overview
Get the total number of CDR records between a start and end datetime.
## Authentication
> **Info**
This function is available via our GraphQL API. You can read more about how to authenticate to this API in [GraphQL API & Authentication](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Method
The GraphQL API does not expose a separate count field. To count records for a period, run the `cdrRecords` query described in [Get CDR Records](https://support.tsgglobal.com/docs/api-reference/reports/cdr-records/get-cdr-records.md) with the maximum page size and follow `paginationInfo.nextCursor` until it is `null`, summing the length of `cdrs` on each page. For very large periods, generate the `exportLink` instead and count the rows of the CSV.
```graphql
query($type: CdrType!, $startDatetime: DateTime!, $endDatetime: DateTime!, $limit: Int, $cursor: String) {
cdrRecords(type: $type, startDatetime: $startDatetime, endDatetime: $endDatetime, limit: $limit, cursor: $cursor) {
paginationInfo {
limit
nextCursor
}
cdrs {
__typename
}
}
}
```
```json
{
"type": "SMS",
"startDatetime": "2026-09-01T00:00:00.000Z",
"endDatetime": "2026-09-02T00:00:00.000Z",
"limit": 1000
}
```
---
# Get CDR Records
Source: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records/get-cdr-records
Markdown: https://support.tsgglobal.com/docs/api-reference/reports/cdr-records/get-cdr-records.md
Last updated: 2024-03-21T15:53:20.027Z
Query call and message detail records with the cdrRecords GraphQL query: arguments, fragments per CDR type, cursor pagination and CSV export.
## Overview
Get call (and messaging) delivery records from your account.
## Authentication
> **Info**
This function is available via our GraphQL API. You can read more about how to authenticate to this API in [GraphQL API & Authentication](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Endpoint
`POST`
## Method
After sending messages or creating calls, you can check those by using the `cdrRecords` query which returns a `paginatedCdrResult` object type. This query is a bit more complex due to the usage of advanced GraphQL features like fragments and cursor based pagination.
Arguments which can be sent are listed below. The exclamation mark (`!`) means a parameter is mandatory, otherwise it's optional:
```
companyId: ID
For which company to list CDRs (only for admin users)
type: CdrType!
The type of the CDR records to list
startDatetime: DateTime!
Will return all records with datetime >= startDatetime
endDatetime: DateTime!
Will return all records with datetime < endDatetime (UTC based), max value is now
cursor: String
Used to paginate, returns results for the passed cursor (if any)
limit: Int
Limit the number of results per page, default is 100, max is 1000
```
### Sample Query
```graphql
query cdrRecordsQuery(
$type: CdrType!
$startDatetime: DateTime!
$endDatetime: DateTime!
$limit: Int
$cursor: String
) {
cdrRecords(
type: $type
startDatetime: $startDatetime
endDatetime: $endDatetime
limit: $limit
cursor: $cursor
) {
exportLink
paginationInfo {
nextCursor
limit
}
cdrs {
... on ApiCdr {
datetime
from
destination
status
charge
type
}
... on MessageCdr {
datetime
fromNumber
toNumber
direction
status
charge
type
}
... on VoiceCdr {
datetime
callId
sourceAni
destinationNumber
didUsed
sessionTime
status
calledRate
charge
callType
aniIi
}
}
}
}
```
In this query GraphQL fragments are used (e.g. `... on MessageCdr { ... }`). They are needed because what we return is a union of types for `cdrs`, and the fields depend on the passed `type`. In our example below we're using `SMS`, but the fragments can be specified for each field in a general query, only change the type.
In our case the type is `SMS`, you send it as an uppercase string. Example of variables sent:
### Sample Variables
```json
{
"type": "SMS",
"startDatetime": "2022-04-26T07:00:00.000Z",
"endDatetime": "2022-04-26T17:13:05.377Z",
"limit": 20
}
```
### Sample Response
```json
{
"data": {
"cdrRecords": {
"cdrs": [
{
"__typename": "MessageCdr",
"account": "ACMEANCHO",
"charge": "0.0095000000",
"cost": "0.0051500000",
"datetime": "2022-01-02T00:00:00Z",
"direction": "SMS / MO Surcharge: T-Mobile - TF",
"fromNumber": "12247512345",
"status": "SENT",
"surcharge": "0.0025000000",
"toNumber": "18447312345",
"uniqueId": "45e868c1-96b2-474c-a60f-98b76d812343"
},
{
"__typename": "MessageCdr",
"account": "ACMEANCHO",
"charge": "0.0010000000",
"cost": "0.0000000000",
"datetime": "2022-01-02T00:00:00Z",
"direction": "SMS / MO: AT&T - LO-ZERO",
"fromNumber": "18134512345",
"status": "SENT",
"surcharge": "0.0000000000",
"toNumber": "19725212345",
"uniqueId": "22854899-1bc9-47b2-9a90-98b76d812344"
}
],
"exportLink": "https://api.portal.tsgglobal.world/export/call_records?sig=abe5dfefb701b284db7b8d18e4673654e788ab42a1ef51bcbc4f153ga218f2fa&end_datetime=2022-01-10T23%3A59%3A59.999Z&fields=account%2Cunique_id%2Ccharge%2Cfrom_number%2Cto_number%2Cstatus%2Cdatetime%2Ccost%2Csurcharge%2Cdirection&start_datetime=2022-01-01T00%3A00%3A00.000Z&type=sms&company_internal_id=ACMEANCHO&new_export=true&user_id=e17bbdf0-e72a-4998-bcfb-8f3e92123456",
"paginationInfo": {
"limit": 100,
"nextCursor": null
}
}
}
}
```
### Pagination
We're using pagination for this endpoint because there can be millions of records for short time frames. To paginate through the results, tweak the previous query so it looks like this (notice the `$limit` and `$cursor` arguments):
```graphql
query($type: CdrType!, $startDatetime: DateTime!, $endDatetime: DateTime!, $companyId: ID, $limit: Int, $cursor: String) {
cdrRecords(type: $type, startDatetime: $startDatetime, endDatetime: $endDatetime, companyId: $companyId, limit: $limit, cursor: $cursor) {
cdrs {
__typename
... on MessageCdr {
account
uniqueId
charge
fromNumber
toNumber
status
datetime
cost
surcharge
direction
}
... on ApiCdr {
account
charge
destination
datetime
status
from
uniqueId
type
}
... on VoiceCdr {
account
charge
destination
datetime
status
uniqueId
aniIi
callId
callType
destinationNumber
sourceAni
calledRate
didUsed
sessionTime
}
}
paginationInfo {
limit
nextCursor
}
exportLink
}
}
```
and variables (`limit=2` and `cursor=null`):
```json
{
"type": "SMS",
"startDatetime": "2022-01-01T00:00:00.000Z",
"endDatetime": "2022-01-10T23:59:59.999Z",
"companyId": "65deb62c-bb16-4a9d-927a-ec1abb37a832",
"limit": 2,
"cursor": null
}
```
The results we get have `paginationInfo` filled differently, notice the `limit` and `nextCursor` properties below:
```json
{
"data": {
"cdrRecords": {
"cdrs": ["...edited for readability..."],
"exportLink": "...edited for readability...",
"paginationInfo": {
"limit": 2,
"nextCursor": "123456"
}
}
}
}
```
We need to use the `nextCursor` value to get the next page, so the variables now look like the following:
```json
{
"type": "SMS",
"startDatetime": "2022-01-01T00:00:00.000Z",
"endDatetime": "2022-01-10T23:59:59.999Z",
"companyId": "65deb62c-bb16-4a9d-927a-ec1abb37a832",
"limit": 2,
"cursor": "123456"
}
```
This will get us the next round of results with another `nextCursor` value. We can paginate until the result we get has `nextCursor: null`; when it's `null` it means we reached the end.
### Exporting CDRs
You can export CDRs by using the `exportLink` which the `cdrRecords` query provides. The easiest way is to click on the link, but you can also do a server-side or client-side download if you want to save the results.
The links in the above example won't work since they're fake but you can generate one with your queries. The export will trigger a CSV file download (via HTTP streams) and include the fields you specified in the query, but the pagination options will be ignored.
Example of an export link:
```
https://api.portal.tsgglobal.world/export/call_records? \
sig=abe5dfefb701b284db7b8d18e4673654e788ab42a1ef51bcbc4f153ga218f2fa& \
fields=account,unique_id,charge,from_number,to_number,status,datetime,cost,surcharge,direction& \
start_datetime=2022-01-01T00:00:00.000Z& \
end_datetime=2022-01-10T23:59:59.999Z& \
type=sms& \
company_internal_id=ACMEANCHO& \
new_export=true& \
user_id=e17bbdf0-e72a-4998-bcfb-8f3e92123456
```
#### Notes
* The export link is protected by a signature and cannot be tampered with; once generated it's public.
* The export process has a timeout of 20 minutes, so if you notice the export timing out reduce the startDatetime and endDatetime period to something manageable and try again.
---
# Compliance & Identity
Source: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity
Markdown: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity.md
Last updated: 2022-11-03T15:04:47.000Z
Toll-Free Verified Sender forms and short code orders through the GraphQL API.
---
# Toll-Free Verified Sender (Order)
Source: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity/toll-free-verified-sender-order
Markdown: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity/toll-free-verified-sender-order.md
Last updated: 2023-03-21T15:12:38.000Z
Submit a Toll-Free Verified Sender Form and list your VSF orders with the GraphQL API. Unverified toll-free numbers are blocked to Canada and throttled to the US.
## Overview
Use this API to create and query the status of current Verified Sender Forms (VSFs). Failure to provide VSFs results in blocking to Canada and lower throughputs to US destinations for toll-free numbers. Submitting a VSF removes the block temporarily until the VSF is either approved, or rejected.
## Authentication
> **Info**
This function is available via our GraphQL API. You can read more about how to authenticate to this API in [GraphQL API & Authentication](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Mutation - to Create a new VSF
```graphql
mutation (
$businessName: String!,
$businessRegisteredAddress: String!,
$businessRegisteredCity: String!,
$businessRegisteredState: String!,
$businessRegisteredZip: String!,
$businessContactFirstName: String!,
$businessContactLastName: String!,
$businessContactEmail: String!,
$businessContactPhone: String!,
$fortune500Or1000Company: String!,
$numbers: [VerifiedSenderFormNumberInput!]!,
$numbersExplanation: String!,
$useCase: String!,
$howDoConsumersOptIn: String!,
$commercialMessages: String!,
$numberPublishedLocation: String!,
$messageSenderWebsite: String!,
$termsAndPrivacy: String!,
$callToAction: String!,
$sampleMessages: [String!]!,
$helpMessageContainsOptOutInstructions: String!,
$stopKeywordIsSupportedAsAnOptOutMethod: String!,
$estimatedMonthlyMessageVolume: String!,
$previouslyAnotherMessagingServiceTraffic: String!,
$previouslyAnotherMessagingServiceContent: String,
$previouslyAnotherMessagingServiceNumbers: [String],
$canadianTrafficMostly: String!,
$covid19Related: String!,
$attachments: [String!]!
) {
submitVerifiedSenderForm(
businessName: $businessName,
businessRegisteredAddress: $businessRegisteredAddress,
businessRegisteredCity: $businessRegisteredCity,
businessRegisteredState: $businessRegisteredState,
businessRegisteredZip: $businessRegisteredZip,
businessContactFirstName: $businessContactFirstName,
businessContactLastName: $businessContactLastName,
businessContactEmail: $businessContactEmail,
businessContactPhone: $businessContactPhone,
fortune500Or1000Company: $fortune500Or1000Company,
numbers: $numbers,
numbersExplanation: $numbersExplanation,
useCase: $useCase,
howDoConsumersOptIn: $howDoConsumersOptIn,
commercialMessages: $commercialMessages,
numberPublishedLocation: $numberPublishedLocation,
messageSenderWebsite: $messageSenderWebsite,
termsAndPrivacy: $termsAndPrivacy,
callToAction: $callToAction,
sampleMessages: $sampleMessages,
helpMessageContainsOptOutInstructions: $helpMessageContainsOptOutInstructions,
stopKeywordIsSupportedAsAnOptOutMethod: $stopKeywordIsSupportedAsAnOptOutMethod,
estimatedMonthlyMessageVolume: $estimatedMonthlyMessageVolume,
previouslyAnotherMessagingServiceTraffic: $previouslyAnotherMessagingServiceTraffic,
previouslyAnotherMessagingServiceContent: $previouslyAnotherMessagingServiceContent,
previouslyAnotherMessagingServiceNumbers: $previouslyAnotherMessagingServiceNumbers,
canadianTrafficMostly: $canadianTrafficMostly,
covid19Related: $covid19Related,
attachments: $attachments
) {
id
finishedAt
insertedAt
name
status
data {
...VerifiedSenderFormFields
}
}
}
fragment VerifiedSenderFormFields on VerifiedSenderFormOrderData {
type
businessName
businessRegisteredAddress
businessRegisteredCity
businessRegisteredState
businessRegisteredZip
businessContactFirstName
businessContactLastName
businessContactEmail
businessContactPhone
fortune500Or1000Company
numbers {
number
}
numbersExplanation
useCase
howDoConsumersOptIn
commercialMessages
numberPublishedLocation
messageSenderWebsite
termsAndPrivacy
callToAction
sampleMessages
helpMessageContainsOptOutInstructions
stopKeywordIsSupportedAsAnOptOutMethod
estimatedMonthlyMessageVolume
previouslyAnotherMessagingServiceTraffic
previouslyAnotherMessagingServiceContent
previouslyAnotherMessagingServiceNumbers
canadianTrafficMostly
covid19Related
}
```
### Sample Arguments
```json
{
"businessName": "[TESTTEST] ACME Inc.",
"businessRegisteredAddress": "[TESTTEST] Street 1B",
"businessRegisteredCity": "[TESTTEST] Denver",
"businessRegisteredState": "Colorado",
"businessRegisteredZip": "123467",
"businessContactFirstName": "John",
"businessContactLastName": "Doe",
"businessContactEmail": "email@acme.org",
"businessContactPhone": "12345678910",
"fortune500Or1000Company": "no",
"numbers": [
{ "number": "12345678910" },
{ "number": "12345678911" }
],
"numbersExplanation": "",
"useCase": "[TESTTEST] actions, discounts, etc.",
"howDoConsumersOptIn": "via website",
"commercialMessages": "yes",
"numberPublishedLocation": "https://acme.org/numbers",
"messageSenderWebsite": "https://acme.org",
"termsAndPrivacy": "https://acme.org/terms",
"callToAction": "Text JOIN to 12345678910 to receive offers",
"sampleMessages": [
"this is a sample message"
],
"helpMessageContainsOptOutInstructions": "yes",
"stopKeywordIsSupportedAsAnOptOutMethod": "yes",
"estimatedMonthlyMessageVolume": "10000",
"previouslyAnotherMessagingServiceTraffic": "yes, on Bandwidth",
"previouslyAnotherMessagingServiceContent": "hello customer",
"previouslyAnotherMessagingServiceNumbers": [
"123456789"
],
"canadianTrafficMostly": "unsure",
"covid19Related": "unsure",
"attachments": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="]
}
```
## Query - to List VSF Orders
Use the below query to list your Verified Sender Form Orders and retrieve the status of the request.
```graphql
query($page: Int, $publicId: String, $type: String, $addedStartDate: DateTime, $addedEndDate: DateTime) {
orders(page: $page, publicId: $publicId, type: $type, addedStartDate: $addedStartDate, addedEndDate: $addedEndDate) {
page
pageSize
totalPages
orders {
id
publicId
name
insertedAt
data {
...VerifiedSenderFormFields
}
}
}
}
fragment VerifiedSenderFormFields on VerifiedSenderFormOrderData {
type
businessName
businessRegisteredAddress
businessRegisteredCity
businessRegisteredState
businessRegisteredZip
businessContactFirstName
businessContactLastName
businessContactEmail
businessContactPhone
fortune500Or1000Company
numbers {
number
}
numbersExplanation
useCase
howDoConsumersOptIn
commercialMessages
numberPublishedLocation
messageSenderWebsite
termsAndPrivacy
callToAction
sampleMessages
helpMessageContainsOptOutInstructions
stopKeywordIsSupportedAsAnOptOutMethod
estimatedMonthlyMessageVolume
previouslyAnotherMessagingServiceTraffic
previouslyAnotherMessagingServiceContent
previouslyAnotherMessagingServiceNumbers
canadianTrafficMostly
covid19Related
}
```
### Sample Arguments
All arguments are optional.
```json
{
"page": 1,
"publicId": "VSF",
"type": "verified_sender_form",
"addedStartDate": "2022-01-01T12:00:00Z",
"addedEndDate": "2022-12-01T12:00:00Z"
}
```
---
# Short Code Submission (Order)
Source: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity/short-code-submission-order
Markdown: https://support.tsgglobal.com/docs/api-reference/compliance-and-identity/short-code-submission-order.md
Last updated: 2023-03-21T15:12:27.000Z
Order short code numbers by submitting the short code form with the GraphQL API, and list your short code orders to track status.
## Overview
This form allows you to order short code numbers for your messaging campaigns.
## Authentication
> **Info**
This function is available via our GraphQL API. You can read more about how to authenticate to this API in [GraphQL API & Authentication](https://support.tsgglobal.com/docs/graphql-api-and-authentication.md).
## Mutation - Submit a short code form (order)
Using a GraphQL mutation you can submit the form, the example command is below. This creates an order which will be verified and the short code numbers will be ordered based on the submitted data.
```graphql
mutation (
$businessName: String!
$businessRegisteredAddress: String!
$businessRegisteredCity: String!
$businessRegisteredState: String!
$businessRegisteredZip: String!
$businessContactFirstName: String!
$businessContactLastName: String!
$businessContactEmail: String!
$businessContactPhone: String!
$useCase: String!
$termsAndConditionsWebsite: String!
$privacyPolicyWebsite: String!
$callToActionLocations: String!
$callToActionLanguage: String!
$optInKeywords: String!
$optInConfirmation: String!
$welcomeMessage: String!
$exampleAlerts: String!
$helpResponseText: String!
$stopResponseText: String!
$customerSupportContactEmail: String!
$customerSupportContactPhone: String!
$customerSupportUrl: String!
$attachments: [String!]!
) {
submitShortcodeForm(
businessName: $businessName,
businessRegisteredAddress: $businessRegisteredAddress,
businessRegisteredCity: $businessRegisteredCity,
businessRegisteredState: $businessRegisteredState,
businessRegisteredZip: $businessRegisteredZip,
businessContactFirstName: $businessContactFirstName,
businessContactLastName: $businessContactLastName,
businessContactEmail: $businessContactEmail,
businessContactPhone: $businessContactPhone,
useCase: $useCase,
termsAndConditionsWebsite: $termsAndConditionsWebsite,
privacyPolicyWebsite: $privacyPolicyWebsite,
callToActionLocations: $callToActionLocations,
callToActionLanguage: $callToActionLanguage,
optInKeywords: $optInKeywords,
optInConfirmation: $optInConfirmation,
welcomeMessage: $welcomeMessage,
exampleAlerts: $exampleAlerts,
helpResponseText: $helpResponseText,
stopResponseText: $stopResponseText,
customerSupportContactEmail: $customerSupportContactEmail,
customerSupportContactPhone: $customerSupportContactPhone,
customerSupportUrl: $customerSupportUrl,
attachments: $attachments,
) {
id
publicId
insertedAt
name
status
statusNote
finishedAt
data {
...ShortcodeFormFields
}
}
}
fragment ShortcodeFormFields on ShortcodeFormOrderData {
type
businessName
businessRegisteredAddress
businessRegisteredCity
businessRegisteredState
businessRegisteredZip
businessContactFirstName
businessContactLastName
businessContactEmail
businessContactPhone
useCase
termsAndConditionsWebsite
privacyPolicyWebsite
callToActionLocations
callToActionLanguage
optInKeywords
optInConfirmation
welcomeMessage
exampleAlerts
helpResponseText
stopResponseText
customerSupportContactEmail
customerSupportContactPhone
customerSupportUrl
attachments
}
```
## Sample arguments
The payload should be formatted like this. Note that `attachments` is an array of base64-encoded images and/or documents.
```json
{
"businessName": "ACME Inc.",
"businessRegisteredAddress": "Street 1B",
"businessRegisteredCity": "Denver",
"businessRegisteredState": "Colorado",
"businessRegisteredZip": "123467",
"businessContactFirstName": "John",
"businessContactLastName": "Doe",
"businessContactEmail": "john.doe@acme.org",
"businessContactPhone": "12345678910",
"useCase": "We'll be sending promo messages using short code numbers",
"termsAndConditionsWebsite": "terms_and_conditions.acme.com",
"privacyPolicyWebsite": "privacy_policy.acme.com",
"callToActionLocations": "top and bottom of the page at acme.com",
"callToActionLanguage": "JOIN NOW, SAVE MONEY, etc.",
"optInKeywords": "JOIN",
"optInConfirmation": "YES",
"welcomeMessage": "Welcome to our shortcode campaign!",
"exampleAlerts": "New offers available! Join now to save 20%.",
"helpResponseText": "This is the HELP menu:\n\nSend STOP to stop all messages.",
"stopResponseText": "You used STOP to stop all messages, you'll no longer receive any promo messages from us.",
"customerSupportContactEmail": "our_support@company.com",
"customerSupportContactPhone": "18881231234",
"customerSupportUrl": "www.our_support.com",
"attachments": [
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
]
}
```
## Query - list short code form orders
To retrieve the status of the request, and to list your short code orders, use the query below.
```graphql
query($page: Int, $publicId: String, $type: String, $addedStartDate: DateTime, $addedEndDate: DateTime) {
orders(page: $page, publicId: $publicId, type: $type, addedStartDate: $addedStartDate, addedEndDate: $addedEndDate) {
page
pageSize
totalPages
orders {
id
publicId
name
insertedAt
data {
...ShortcodeFormFields
}
}
}
}
fragment ShortcodeFormFields on ShortcodeFormOrderData {
type
businessName
businessRegisteredAddress
businessRegisteredCity
businessRegisteredState
businessRegisteredZip
businessContactFirstName
businessContactLastName
businessContactEmail
businessContactPhone
useCase
termsAndConditionsWebsite
privacyPolicyWebsite
callToActionLocations
callToActionLanguage
optInKeywords
optInConfirmation
welcomeMessage
exampleAlerts
helpResponseText
stopResponseText
customerSupportContactEmail
customerSupportContactPhone
customerSupportUrl
attachments
}
```
And the variables look like this:
```json
{
"page": 1,
"publicId": "SCF",
"type": "shortcode_form"
}
```
You can do a more detailed search, e.g. by using the full `publicId`:
```json
{
"page": 1,
"publicId": "SCF-5XXY1YJHLK",
"type": "shortcode_form"
}
```
You can also specify a date range:
```json
{
"page": 1,
"publicId": "SCF",
"type": "shortcode_form",
"addedStartDate": "2022-01-01T12:00:00Z",
"addedEndDate": "2022-12-01T12:00:00Z"
}
```
---
# GraphQL API & Authentication
Source: https://support.tsgglobal.com/docs/graphql-api-and-authentication
Markdown: https://support.tsgglobal.com/docs/graphql-api-and-authentication.md
Last updated: 2024-03-21T15:51:32.973Z
Describes how to authenticate to our GraphQL API.
## What is GraphQL?
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
You can learn more about the GraphQL framework here:
For testing it would be good to use [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) or some other similar API client.
## How do I access the TSG Global GraphQL API?
> **Danger**
This authentication method is different than the API key authentication method used for other TSG Global services, and the TNID service.
You can generate a Bearer token to access our GraphQL API using the username and password you use to access our [Customer Portal](https://customer-portal.tsgglobal.com). This token lasts for 7 days.
## Generate Bearer Token
`POST` `https://api.portal.tsgglobal.world/account/login`
#### Request Body
| Name | Type | Description |
| ------------------------------------------ | ------ | ------------------------ |
| email\* | string | Your user email address. |
| password\* | string | Your password. |
### 200: OK
```javascript
{
"token": "POAPK_*********",
"user": {
"email": "test.user@tsgglobal.com",
"first_name": "Test",
"id": "*****",
"last_name": "User",
"level": "basic_user"
}
}
```
### 401: Unauthorized Invalid email or password.
```javascript
{
"errors": [
{
"id": "unauthorized",
"message": "Invalid email or password."
}
]
}
```
When you query the API, you will want to pass your credentials in the header, with the header name "Authorization" and the value as "Bearer \".
If you are missing these credentials, please email us at:
## Where can I test the GraphQL API and view more documentation?
You can test various features and view additional documentation in the GraphiQL interface we provide here:
## What URL should I use to perform my queries and mutations?
Please use: (note this is different than the GraphiQL UI).
---
# Changelog
Source: https://support.tsgglobal.com/docs/changelog
Markdown: https://support.tsgglobal.com/docs/changelog.md
Dated log of changes to the TSG Global APIs and to this documentation.
Newest first. This log starts on 2026-09-11; API changes before that date were not recorded here.
## 2026-09-11: documentation
* New pages: [API Quick Reference](https://support.tsgglobal.com/docs/api-quick-reference.md), [AI Assistants & MCP](https://support.tsgglobal.com/docs/ai-assistants-and-mcp.md) and this changelog.
* An OpenAPI 3.1 description of the REST APIs (SMS, MMS, MMS templates, number configuration) is published in GitBook as `tsg-global-rest`; see OpenAPI Specification.
* Corrections: `PSTN` (not `PTSN`) in the Destination Priority examples; the staging MMS-over-SMTP section no longer repeats the SMPP settings; the inbound SMS webhook page now names the real `webhook_url` field; the `unauthenticated` error type definition; invalid JSON in the Receive an SMS Message example; placeholder responses on Send an MMS Message, Disable SMS and Disable MMS replaced with real ones; the MMS Templates quickstart code restored to readable blocks; the template example without placeholders now shows an empty placeholder list; nested code fences fixed on Receive DLRs, Get Number Information and List Destination Priority; the stray scheduling hint removed from Delete Destination Priority; Get Count of CDR Records now explains how to count; typos on the Verified Sender and Short Code pages.
* Every page now carries a description, which also improves `llms.txt` and MCP search results.
## Known gaps
* Production SMPP hostname and per-account rate limits are not published; contact .