This guide walks you through sending your first SMS using the InstaMessage Messaging API.

You’ll learn how to authenticate, send SMS messages using text or templates, personalise content using injected_fields, and understand the API response.

To send SMS messages through InstaMessage, you’ll need the following:

If you're new to InstaMessage, contact our sales team to set up your account:

[email protected]

To send SMS messages, you need at least one SMS-capable number connected to your account.

1. Go to Admin → Purchase Numbers
2. Choose a number that supports SMS
3. Click Buy

This number becomes your default SMS originator.

You can set an alphanumeic sender ID under Admin → SMS Settings.

Carrier and country rules apply.

You can find your API key in the InstaMessage dashboard:

1. Go to Admin → API
2. Select Show Key under API Live Key
3. Copy your API Key

Admin → API

Your API key is tied to your InstaMessage account and authorises access to all InstaMessage APIs.

Important: Treat your API key like a password. Never share it publicly or commit it to source control.

Each account has a single active API key. Subaccounts and environments will be supported in future.

InstaMessage uses API key authentication.

Each API request must include a valid API key issued to your account.

Authorization: Bearer YOUR_API_KEY

All SMS messages are sent using the unified messaging endpoint:

POST https://api.instamessage.co.uk/v1/messages

Required fields

Conditional fields

SMS templates are created and managed in the InstaMessage dashboard.

To find a template ID:

1. Go to Admin → Templates
2. Create or select an existing SMS template
3. Copy the template ID shown on the template table or in the template details

SMS templates allow you to standardise content, reuse messaging, and manage opt-out behaviour centrally.

The template ID is used when sending an SMS with message_type: "template".

SMS templates can be rendered using stored contact fields and/or injected_fields.

{
  "channel": "sms",
  "to": "+447123456789",
  "message_type": "template",
  "template": {
    "id": "TmpZ****************"
  }
}

• injected_fields are applied at send time and do not modify stored contact data.
• If a contact exists, InstaMessage can also use stored contact fields and custom attributes.
• If a field exists in both places, injected_fields takes precedence.

• Contact first_name = "Adam"
• You send injected_fields.first_name = "Eve"
• {{first_name}} renders as "Eve"

SMS templates use named placeholders such as {{first_name}}.

Placeholders can be filled from:

• stored contact data (fixed fields + custom attributes), and/or
• injected_fields included with your API request

If a value exists in both places, injected_fields overrides stored values.

{
  "channel": "sms",
  "to": "+447123456789",
  "message_type": "template",
  "template": {
    "id": "TmpZ****************"
  },
  "injected_fields": {
    "first_name": "Alex",
    "order_id": "12345"
  }
}

Opt-out URLs are not appended to template-based SMS messages. Templates must include opt-out content explicitly if required.

Messages are charged per SMS segment, based on encoding and length.

A single SMS supports up to 160 characters when using standard GSM-7 encoding.
If the message exceeds this limit, it will be split into multiple concatenated SMS segments (each charged separately).

For concatenated messages:

• GSM-7 encoding allows 153 characters per segment
• Messages containing emojis or special characters use UCS-2 encoding and allow 70 characters (or 67 characters per segment when concatenated)

Segment limits and encoding are determined automatically based on message content and carrier support.

• SMS messages are sent immediately
• Messages are charged per message segment
• Originators must be approved

InstaMessage reports delivery outcomes and inbound replies using account-level webhooks.

Webhooks are configured once per account and apply to all messages sent via the API.

Delivery status webhooks

When a message status updates (such as delivered or failed), InstaMessage sends a delivery status webhook to your configured webhook URL.

For SMS you’ll typically receive a single final outcome (such as delivered or failed).

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "sms",
  "to": "+447123456789",
  "status": "delivered",
  "timestamp": "2026-01-14T12:03:11Z"
}

If you miss a webhook delivery, you can retrieve the latest delivery status using the message ID returned when the message was created.

See: Delivery tracking → Delivery Receipts & Message Status

This endpoint acts as a recovery mechanism if a webhook delivery is missed.

{
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "sms",
  "to": "+447123456789",
  "status": "delivered",
  "created_at": "2026-01-14T12:02:10Z",
  "delivered_at": "2026-01-14T12:03:11Z"
}

You can only use an originator (phone number or approved alphanumeric Sender ID) that is assigned to your InstaMessage account.

• If sms_originator is omitted, InstaMessage will use your primary SMS number
• If sms_originator is provided and approved, that value will be used
• If sms_originator is invalid or unapproved, InstaMessage will fall back to the account’s default SMS originator

Below is a basic example in multiple languages.

curl -X POST "https://api.instamessage.co.uk/v1/messages" \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+447123456789",
    "message_type": "text",
    "text": "Your delivery is on its way."
  }'

Use placeholders inside your text and supply values via injected_fields.

{
  "channel": "sms",
  "to": "+447123456789",
  "message_type": "text",
  "text": "Hi {{first_name}}, your order {{order}} is out for delivery today.",
  "injected_fields": {
    "first_name": "Alex",
    "order": "12345"
  }
}

Rendered output:

Hi Alex, your order 12345 is out for delivery today.

{
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123"
}

Delivery status and timestamps are provided asynchronously via webhooks or can be retrieved using the message ID.

Now that you can send SMS, you may want to:

• Delivery tracking → Delivery Receipts & Message Status
• Customer replies → Inbound Messages & Replies
• Webhooks → Webhook Quick-Start

SMS is the fastest way to start sending messages with InstaMessage - and you can expand to other channels at any time.