Send a message

POST

notify

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const response = await client.notify.send({
    template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to: "+30123456789",
    variables: { foo: "bar" },
  });

  console.log(response.id);
}

main();

package main

import (
	"context"
	"fmt"

	"github.com/prelude-so/go-sdk"
	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	response, err := client.Notify.Send(context.TODO(), prelude.NotifySendParams{
		TemplateID: prelude.F("template_01k8ap1btqf5r9fq2c8ax5fhc9"),
		To: prelude.F("+30123456789"),
		Variables: prelude.F(map[string]string{
			"foo": "bar",
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", response.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

response = client.notify.send(
    template_id="template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to="+30123456789",
    variables={
        "foo": "bar"
    },
)

print(response.id)

{
  "id": "tx_01k8ap1btqf5r9fq2c8ax5fhc9",
  "to": "+33612345678",
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "variables": {
    "order_id": "12345",
    "amount": "$49.99"
  },
  "expires_at": "2025-12-25T18:00:00Z",
  "created_at": "2025-10-24T12:00:00Z",
  "from": "YourBrand",
  "callback_url": "https://your-app.com/webhooks/notify",
  "correlation_id": "order-12345",
  "schedule_at": "2025-12-25T08:00:00-05:00",
  "estimated_segment_count": 1,
  "encoding": "GSM-7"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const response = await client.notify.send({
    template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to: "+30123456789",
    variables: { foo: "bar" },
  });

  console.log(response.id);
}

main();

package main

import (
	"context"
	"fmt"

	"github.com/prelude-so/go-sdk"
	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	response, err := client.Notify.Send(context.TODO(), prelude.NotifySendParams{
		TemplateID: prelude.F("template_01k8ap1btqf5r9fq2c8ax5fhc9"),
		To: prelude.F("+30123456789"),
		Variables: prelude.F(map[string]string{
			"foo": "bar",
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", response.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

response = client.notify.send(
    template_id="template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to="+30123456789",
    variables={
        "foo": "bar"
    },
)

print(response.id)

The variables object must contain exactly the variables defined in your template, no more, no less. Sending variables that don’t belong to the template (for example, a senderName variable when the template only expects smsShortLink) will return an invalid_template_variables error. This strictness helps catch typos in variable names and prevents sending messages with unintended placeholders.

Common Use Cases

Send an immediate transactional message

const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+33612345678",
  variables: { 
    order_id: "12345",
    amount: "$49.99" 
  },
  callback_url: "https://your-app.com/webhooks/notify"
});

Schedule a marketing campaign

const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+15551234567",
  schedule_at: "2025-12-25T10:00:00Z",
  variables: { 
    promotion: "Holiday Sale",
    discount: "20%" 
  }
});

// Check when it will actually be sent (may be adjusted for compliance)
console.log(response.schedule_at); // "2025-12-25T08:00:00-05:00"

Send with custom sender ID

const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+4412345678",
  from: "YourBrand",
  variables: { name: "John" }
});

Send via specific channel

const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+33612345678",
  preferred_channel: "whatsapp", // or "sms", "rcs"
  variables: { message: "Hello!" }
});

Error Handling

The Notify API returns specific error codes for different scenarios:

Error Code	Description	Action
`category_forbidden`	Message category forbidden in country	Use a different template
`insufficient_balance`	Account balance is too low	Top up your account
`invalid_phone_number`	Phone number format is invalid	Validate phone number format
`invalid_template_id`	Template ID is invalid or too long	Check the ID length and format
`invalid_template_variables`	Template variables are invalid, missing, or include unknown variables not defined in the template	Provide a JSON object containing exactly the variables required by the template
`template_not_found`	Template ID doesn’t exist	Check template ID with your CSM
`template_not_registered_in_country`	Template is not registered for the target country	Register the template for this country or use a different template
`template_not_validated`	Marketing template not approved	Contact your CSM
`unsubscribed`	Recipient has opted out of marketing messages	Update your records and don’t retry

For a complete list of errors, see the Error documentation.

WhatsApp 2-Way Messaging - Receive inbound messages and send replies
WhatsApp Media - Attach an image, video, or document to a WhatsApp template
Webhooks - Receive delivery updates, inbound messages, and subscription events
Marketing Compliance - Understand compliance rules by country
Subscription Management - Handle opt-out/opt-in flows
Scheduling - Advanced scheduling and timezone handling

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

string

required

The recipient's phone number in E.164 format.

Example:

"+33612345678"

template_id

string

required

The template identifier configured by your Customer Success team.

Example:

"template_01k8ap1btqf5r9fq2c8ax5fhc9"

from

string

The Sender ID. Must be approved for your account.

locale

string

A BCP-47 formatted locale string with the language the text message will be sent to. If there's no locale set, the language will be determined by the country code of the phone number. If the language specified doesn't exist, the default set on the template will be used.

Examples:

"el-GR"

"fr-FR"

variables

object

The variables to be replaced in the template.

Show child attributes

Example:

{ "order_id": "12345", "amount": "$49.99" }

expires_at

string<date-time>

The message expiration date in RFC3339 format. The message will not be sent if this time is reached.

Example:

"2025-12-25T18:00:00Z"

schedule_at

string<date-time>

Schedule the message for future delivery in RFC3339 format. Marketing messages can be scheduled up to 90 days in advance and will be automatically adjusted for compliance with local time window restrictions.

Example:

"2025-12-25T10:00:00Z"

callback_url

string

The URL where webhooks will be sent for message delivery events.

Example:

"https://your-app.com/webhooks/notify"

correlation_id

string

A user-defined identifier to correlate this message with your internal systems. It is returned in the response and any webhook events that refer to this message.

Maximum string length: 80

Example:

"order-12345"

preferred_channel

enum<string>

The preferred channel to be used in priority for message delivery. If the channel is unavailable, the system will fallback to other available channels.

Available options:

sms,

rcs,

whatsapp

Example:

"whatsapp"

document

object

A media attachment to include in the message header. Supported on WhatsApp templates registered with a DOCUMENT, IMAGE, or VIDEO header. The media type is determined by the template's registered header format; send the matching file type for each.

DOCUMENT headers accept PDF and other document formats; filename is required and displayed to the recipient.
IMAGE headers accept .png, .jpg, .jpeg, and .webp URLs; filename is ignored.
VIDEO headers accept .mp4 and .3gp URLs; filename is ignored.

Show child attributes

max_auto_retries

integer

Maximum number of automatic retry attempts across channels for this send, in addition to the first attempt. For example, 2 allows up to 3 total delivery attempts. Lower values reduce delivery cost on hard-to-reach numbers at the expense of deliverability. When omitted, your account's configured default applies.

Required range: 0 <= x <= 6

Example:

2

Callbacks

POST

{$request.body#/callback_url}webhook_event

Body

application/json

string

required

The event identifier.

Example:

"evt_01hynf45qvevj844m9az2x2f3c"

created_at

string<date-time>

required

The event creation date.

Example:

"2028-01-01T00:00:00Z"

type

string

required

The event type.

Example:

"<message_type>"

payload

object

required

The event payload.

Show child attributes

Response

Your server accepted the event and will process it.

Response

string

required

The message identifier.

Example:

"tx_01k8ap1btqf5r9fq2c8ax5fhc9"

string

required

The recipient's phone number in E.164 format.

Example:

"+33612345678"

template_id

string

required

The template identifier.

Example:

"template_01k8ap1btqf5r9fq2c8ax5fhc9"

variables

object

required

The variables to be replaced in the template.

Show child attributes

Example:

{ "order_id": "12345", "amount": "$49.99" }

expires_at

string<date-time>

required

The message expiration date in RFC3339 format.

Example:

"2025-12-25T18:00:00Z"

created_at

string<date-time>

required

The message creation date in RFC3339 format.

Example:

"2025-10-24T12:00:00Z"

from

string

The Sender ID used for this message.

Example:

"YourBrand"

callback_url

string

The callback URL where webhooks will be sent.

Example:

"https://your-app.com/webhooks/notify"

correlation_id

string

A user-defined identifier to correlate this message with your internal systems.

Maximum string length: 80

Example:

"order-12345"

schedule_at

string<date-time>

When the message will actually be sent in RFC3339 format with timezone offset. For marketing messages, this may differ from the requested schedule_at due to automatic compliance adjustments.

Example:

"2025-12-25T08:00:00-05:00"

estimated_segment_count

integer

The estimated number of SMS segments for this message. This value is not contractual; the actual segment count will be determined after the SMS is sent by the provider. Only present for SMS messages.

Example:

1

encoding

enum<string>

The SMS encoding type based on message content. GSM-7 supports standard characters (up to 160 chars per segment), while UCS-2 supports Unicode including emoji (up to 70 chars per segment). Only present for SMS messages.

Available options:

GSM-7,

UCS-2

Example:

"GSM-7"

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const response = await client.notify.send({
    template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to: "+30123456789",
    variables: { foo: "bar" },
  });

  console.log(response.id);
}

main();

package main

import (
	"context"
	"fmt"

	"github.com/prelude-so/go-sdk"
	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	response, err := client.Notify.Send(context.TODO(), prelude.NotifySendParams{
		TemplateID: prelude.F("template_01k8ap1btqf5r9fq2c8ax5fhc9"),
		To: prelude.F("+30123456789"),
		Variables: prelude.F(map[string]string{
			"foo": "bar",
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", response.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

response = client.notify.send(
    template_id="template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to="+30123456789",
    variables={
        "foo": "bar"
    },
)

print(response.id)

{
  "id": "tx_01k8ap1btqf5r9fq2c8ax5fhc9",
  "to": "+33612345678",
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "variables": {
    "order_id": "12345",
    "amount": "$49.99"
  },
  "expires_at": "2025-12-25T18:00:00Z",
  "created_at": "2025-10-24T12:00:00Z",
  "from": "YourBrand",
  "callback_url": "https://your-app.com/webhooks/notify",
  "correlation_id": "order-12345",
  "schedule_at": "2025-12-25T08:00:00-05:00",
  "estimated_segment_count": 1,
  "encoding": "GSM-7"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

Documentation

API Reference

Common Use Cases

Error Handling

Authorizations

Body

Callbacks

Body

Response

Response

​Common Use Cases

​Error Handling

​Related Documentation

Authorizations

Body

Callbacks

Body

Response

Response

Common Use Cases

Error Handling

Related Documentation