# Send an MMS Message Using Templates ## 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 Templates? ### 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 hit 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 \ You can find your messaging API key in the TSG Global Customer Portal under your account settings. *** 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" %} curl -X POST -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": "", "content\_type": "image/png", "content\_location": "brand-logo.png" } ] } } }' {% endtab %} {% tab title="Python" %} import requests resp = requests.post( "", 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": "", "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" %} curl -X POST -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": "" } } } }' {% endtab %} {% tab title="Python" %} preview = requests.post( f"", 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": "", }, }, } }, ) 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" %} curl -X POST -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": "" }, "request\_delivery\_reports": true } } }' {% endtab %} {% tab title="Python" %} send = requests.post( f"", 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": "", }, "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: {% content-ref url="/pages/VH6BURy3AyAZj6IM64Qp" %} [Create MMS Template](/api-reference/programmable-mms/send-an-mms-message-using-templates/create-mms-template.md) {% endcontent-ref %} {% content-ref url="/pages/yFXmV06rXNKCjfOtshvl" %} [Preview MMS Template](/api-reference/programmable-mms/send-an-mms-message-using-templates/preview-mms-template.md) {% endcontent-ref %} {% content-ref url="/pages/woVqRCJV1Q4ev2vh3Y8t" %} [Send MMS Using Template](/api-reference/programmable-mms/send-an-mms-message-using-templates/send-mms-using-template.md) {% endcontent-ref %} {% content-ref url="/pages/zmHfsMtBolMZDDxC3ptI" %} [List MMS templates](/api-reference/programmable-mms/send-an-mms-message-using-templates/list-mms-templates.md) {% endcontent-ref %} {% content-ref url="/pages/kJzj1j6Rtv8oSxXoxSyg" %} [Get Single MMS template](/api-reference/programmable-mms/send-an-mms-message-using-templates/get-single-mms-template.md) {% endcontent-ref %} {% content-ref url="/pages/ER4MwX31FbSEVDbQ8aI2" %} [Delete MMS Template](/api-reference/programmable-mms/send-an-mms-message-using-templates/delete-mms-template.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tsgglobal.com/api-reference/programmable-mms/send-an-mms-message-using-templates.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.