Send an MMS Message Using Templates

Why MMS templates exist, common use cases, and a three-call quickstart: create a template, preview it, send it.

Overview

This functionality enables users to create MMS templates (both content and attachments) which they can use to send MMS messages in a simpler and more performant (less resource intensive) way.

Why Use MMS Templates?

MMS templates let you define your message content and media attachments once, then send personalized messages at scale, without re-uploading media or rebuilding payloads for every request.

• Faster sends: pre-staged media means smaller payloads and lower latency per message. Skip the base64 encoding and inline attachment overhead.
• Personalization at scale: use {placeholder} syntax to inject per-recipient details (names, appointment times, order numbers) into both subject lines and message bodies.
• Brand consistency: lock down approved copy and creative assets in a template so every message stays on-brand, regardless of who triggers the send.
• Preview before you send: render a fully-resolved preview with real placeholder values to catch issues before they reach your customers' phones.
• Simpler integration: your send call is just a template ID, a recipient list, and a params object. No need to reconstruct the full message every time.

Common Use Cases

Appointment Reminders with Rich Media

A healthcare provider creates a template with their clinic's logo and a message: "Hi {patient_name}, your appointment with {doctor_name} is on {date} at {time}. Reply CONFIRM or call us to reschedule." One template, thousands of personalized reminders, each with consistent branding and a professional look that SMS can't match.

Marketing Campaigns with Branded Creative

A retail brand launches a flash sale. Their marketing team uploads a promotional image once, locks the copy, "{first_name}, our Summer Sale starts now! Show this MMS in-store for an extra 10% off.", and triggers sends to segmented customer lists via API. No re-uploading the image per batch. No copy drift between segments.

Transactional Notifications

An e-commerce platform sends order confirmations with a product thumbnail: "Thanks {customer_name}! Your order #{order_id} has shipped. Track it here: {tracking_url}" The product image and layout stay consistent across millions of orders, while every detail is unique per customer.

Quickstart: Send Your First Template MMS

Go from zero to a delivered MMS in three API calls. This guide walks through the full lifecycle: create a template, preview it, and send it.

Prerequisites

• A TSG Global account with MMS enabled
• Your messaging API key (found in Customer Portal, Account)
• A provisioned phone number capable of sending MMS

Authentication

All requests require your TSG Global messaging API key passed via the Authorization header:

Authorization: Bearer <api_key>

Step 1: Create a Template

Define your message copy with placeholders and attach media. Placeholders use {variable_name} syntax and will be replaced with real values when you preview or send.

curl -X POST https://mmsc.tsgglobal.world/mms/templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "data": {
      "type": "mms-template",
      "attributes": {
        "name": "order-confirmation",
        "subject_template": "Order #{order_id} Confirmed",
        "body_template": "Hi {customer_name}, your order #{order_id} has shipped! Track it here: {tracking_url}",
        "parts": [
          {
            "kind": "uri",
            "uri": "https://cdn.example.com/brand-logo.png",
            "content_type": "image/png",
            "content_location": "brand-logo.png"
          }
        ]
      }
    }
  }'

import requests

resp = requests.post(
    "https://mmsc.tsgglobal.world/mms/templates",
    headers={"Content-Type": "application/json", "Authorization": "Bearer <api_key>"},
    json={
        "data": {
            "type": "mms-template",
            "attributes": {
                "name": "order-confirmation",
                "subject_template": "Order #{order_id} Confirmed",
                "body_template": "Hi {customer_name}, your order #{order_id} has shipped! Track it here: {tracking_url}",
                "parts": [
                    {
                        "kind": "uri",
                        "uri": "https://cdn.example.com/brand-logo.png",
                        "content_type": "image/png",
                        "content_location": "brand-logo.png",
                    }
                ],
            },
        }
    },
)

template = resp.json()
template_id = template["data"]["id"]
print(f"Created template: {template_id}")

Save the returned template_id; you'll need it for the next two steps.

Step 2: Preview (Optional but Recommended)

Render the template with real values to verify everything looks right, without actually sending anything.

curl -X POST https://mmsc.tsgglobal.world/mms/templates/TEMPLATE_ID/preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "data": {
      "type": "mms-template-preview-req",
      "attributes": {
        "from": "18005551234",
        "to": ["19175559876"],
        "params": {
          "customer_name": "Jane",
          "order_id": "78432",
          "tracking_url": "https://track.example.com/78432"
        }
      }
    }
  }'

preview = requests.post(
    f"https://mmsc.tsgglobal.world/mms/templates/{template_id}/preview",
    headers={"Content-Type": "application/json", "Authorization": "Bearer <api_key>"},
    json={
        "data": {
            "type": "mms-template-preview-req",
            "attributes": {
                "from": "18005551234",
                "to": ["19175559876"],
                "params": {
                    "customer_name": "Jane",
                    "order_id": "78432",
                    "tracking_url": "https://track.example.com/78432",
                },
            },
        }
    },
)

print(preview.json())

Check the response. The subject should read "Order #78432 Confirmed" and the body should start with "Hi Jane, your order #78432 has shipped!"

Step 3: Send It

Same shape as the preview call; just swap the endpoint from /preview to /send.

curl -X POST https://mmsc.tsgglobal.world/mms/templates/TEMPLATE_ID/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "data": {
      "type": "mms-template-send-req",
      "attributes": {
        "from": "18005551234",
        "to": ["19175559876"],
        "params": {
          "customer_name": "Jane",
          "order_id": "78432",
          "tracking_url": "https://track.example.com/78432"
        },
        "request_delivery_reports": true
      }
    }
  }'

send = requests.post(
    f"https://mmsc.tsgglobal.world/mms/templates/{template_id}/send",
    headers={"Content-Type": "application/json", "Authorization": "Bearer <api_key>"},
    json={
        "data": {
            "type": "mms-template-send-req",
            "attributes": {
                "from": "18005551234",
                "to": ["19175559876"],
                "params": {
                    "customer_name": "Jane",
                    "order_id": "78432",
                    "tracking_url": "https://track.example.com/78432",
                },
                "request_delivery_reports": True,
            },
        }
    },
)

result = send.json()
print(f"Message sent! ID: {result['data']['id']}")

That's it: three calls from template creation to a delivered MMS.

What's Next?

• List your templates: GET /mms/templates to see all saved templates
• Clean up: DELETE /mms/templates/:id to remove templates you no longer need
• Send at scale: pass multiple numbers in the to array to reach a list in one call
• Track delivery: set request_delivery_reports: true and configure a webhook to receive DLRs

Relevant pages: