> For the complete documentation index, see [llms.txt](https://docs.tsgglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tsgglobal.com/api-reference/programmable-mms/send-an-mms-message-using-templates.md). # 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: ```http Authorization: Bearer ``` *** #### 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. {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://mmsc.tsgglobal.world/mms/templates \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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" } ] } } }' ``` {% endtab %} {% tab title="Python" %} ```python import requests resp = requests.post( "https://mmsc.tsgglobal.world/mms/templates", headers={"Content-Type": "application/json", "Authorization": "Bearer "}, 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}") ``` {% endtab %} {% endtabs %} 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. {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://mmsc.tsgglobal.world/mms/templates/TEMPLATE_ID/preview \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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" } } } }' ``` {% endtab %} {% tab title="Python" %} ```python preview = requests.post( f"https://mmsc.tsgglobal.world/mms/templates/{template_id}/preview", headers={"Content-Type": "application/json", "Authorization": "Bearer "}, 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()) ``` {% endtab %} {% endtabs %} 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`. {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://mmsc.tsgglobal.world/mms/templates/TEMPLATE_ID/send \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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 } } }' ``` {% endtab %} {% tab title="Python" %} ```python send = requests.post( f"https://mmsc.tsgglobal.world/mms/templates/{template_id}/send", headers={"Content-Type": "application/json", "Authorization": "Bearer "}, 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']}") ``` {% endtab %} {% endtabs %} 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: