​

Overview

​

Delivery lifecycle signals

• sms.otp
• message.queued
• message.sent
• message.delivered
• message.scheduled
• message.failed
• message.canceled
• message.batch

​

High-impact practices

• Send only valid E.164 numbers that your project is allowed to use.
• Keep OTP and transactional content short.
• Use Idempotency-Key on send/create operations.
• Persist webhook payloads and deduplicate by event id.
• Return a 2xx response quickly from webhook handlers.

​

Template and content strategy

• Prefer templates when the same flow is reused.
• Keep placeholder names stable across every locale variant.
• Put brand context at the start of the message.
• Keep locale coverage aligned with the countries you actually send to.
• Use tags to segment traffic by use case or campaign.

{
  "to": "+5511999999999",
  "content": "Rewrite: your verification code is 123456",
  "tags": {
    "use_case": "otp_login",
    "template_version": "v3"
  }
}

​

Failure handling

• Retry only 429 and transient 5xx scenarios.
• Treat 400 validation failures as permanent until the payload is fixed.
• Treat 403 billing/subscription blocks as operational issues, not retryable sends.
• Inspect message.failed webhook payloads for provider-facing error details.

​

Related guides

• Errors & retries
• Template i18n
• Webhooks introduction