Skip to main content
POST
/
v2
/
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();

{
  "id": "tx_01k8ap1btqf5r9fq2c8ax5fhc9",
  "from": "YourBrand",
  "to": "+33612345678",
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "variables": {
    "order_id": "12345",
    "amount": "$49.99"
  },
  "callback_url": "https://your-app.com/webhooks/notify",
  "correlation_id": "order-12345",
  "expires_at": "2025-12-25T18:00:00Z",
  "schedule_at": "2025-12-25T08:00:00-05:00",
  "created_at": "2025-10-24T12:00:00Z"
}
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();

​
Common Use Cases

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"
});

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"

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

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

​
Error Handling

The Notify API returns specific error codes for different scenarios:
Error CodeDescriptionAction
unsubscribedRecipient has opted out of marketing messagesUpdate your records and don’t retry
template_not_foundTemplate ID doesn’t existCheck template ID with your CSM
invalid_phone_numberPhone number format is invalidValidate phone number format
insufficient_balanceAccount balance is too lowTop up your account
template_not_validatedMarketing template not approvedContact your CSM
category_forbiddenMessage category forbidden in countryUse a different template
For a complete list of errors, see the Error documentation.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
to
string
required

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

Examples:

"+33612345678"

​
template_id
string
required

The template identifier configured by your Customer Success team.

Examples:

"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.

Examples:
{ "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.

Examples:

"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.

Examples:

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

​
callback_url
string

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

Examples:

"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 length: 80
Examples:

"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,
whatsapp
Examples:

"whatsapp"

Response

OK

​
id
string
required

The message identifier.

Examples:

"tx_01k8ap1btqf5r9fq2c8ax5fhc9"

​
to
string
required

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

Examples:

"+33612345678"

​
template_id
string
required

The template identifier.

Examples:

"template_01k8ap1btqf5r9fq2c8ax5fhc9"

​
variables
object
required

The variables to be replaced in the template.

Examples:
{ "order_id": "12345", "amount": "$49.99" }
​
expires_at
string<date-time>
required

The message expiration date in RFC3339 format.

Examples:

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

​
created_at
string<date-time>
required

The message creation date in RFC3339 format.

Examples:

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

​
from
string

The Sender ID used for this message.

Examples:

"YourBrand"

​
callback_url
string

The callback URL where webhooks will be sent.

Examples:

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

​
correlation_id
string

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

Maximum length: 80
Examples:

"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.

Examples:

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