马来西亚短信 API
从你自己的系统直接发短信

拿来做什么

• 验证码（OTP）：登录、结账时发，从 5 位短号码发出。
• 订单和派送通知：由你系统里的状态变化触发。
• 预约提醒：排程系统提前一天发。
• 内部警报：定时任务出问题就发短信给你，邮件和推送收不到时短信照样到。
• 从 CRM 直接发营销短信：不用导出 CSV 再贴进网页。

大多数短信 API 做错的地方

你的 HTTP 客户端有超时，我们这边也有网络。迟早会遇到这种情况：请求在我们已经建好短信、但你还没收到回应时超时了 —— 你的重试逻辑就会再发一次。没有防护的话，就是扣两次钱、每个收件人收到两条，而且两次都退不了，因为运营商两次都收了费。

每个发送请求都接受 Idempotency-Key 请求头。同一个请求重试多少次都可以：第一次真正发送，之后每一次都返回完全相同的结果（包括同一个短信 ID），不会重复扣费。

curl https://hantarsms.com/api/v1/messages \
  -H "X-API-Key: $HANTARSMS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48213-reminder" \
  -d '{"to":["60123456789"],"text":"您的订单 #48213 已可取货。"}'

逐个号码的送达报告

活动效果不好的时候，总数没什么用。API 会返回每一个号码的结果，并且把很多平台混在一起的两种状态分开：

把 rejected 并进 undelivered 的话，账单根本对不上 —— 一个要收费，一个不收。

还有这些

• 可以直接判断的错误码。insufficient_balance、content_blocked 这类稳定的机器码，不用去匹配一段文字。
• 品牌词筛查。平台可能拦截或标记含受保护国际品牌名的短信 —— 电信每段罚 RM1.50 并向发送方追讨。把它当安全网，不是保证。
• 查询余额的接口，额度快用完时可以先提醒自己。
• 多把密钥、可以分别停用 —— 测试环境和正式环境分开。
• 和网页后台同价。标准每段 RM0.20，量大自动降价。没有 API 附加费，没有平台月费。

完整文档

接口、参数、所有错误码，以及 PHP、Python、Node.js、Java 的可运行示例，都在 API 文档。不用注册就能看 —— 注册前先看一眼，确认适不适合你的系统。用 WordPress 的话，WordPress 插件不用写代码就能接上验证码、WooCommerce 订单短信和营销群发。

常见问题

API 要月费吗？

不用。API 每段的价格和网页后台一样，没有平台费、没有最低用量、也没有单独的 API 套餐，只按短信收费。

请求超时后我重试，会怎样？

如果带了 Idempotency-Key 请求头，什么都不会多发 —— 重试会返回原来的结果和同一个短信 ID，只扣一次钱。没带这个请求头的话，重试会被当成一条新短信，所以每个请求都要带上。

可以用 API 发验证码吗？

可以，这是最主要的用途之一。短信从共享的 5 位短号码发出，正是用户习惯收验证码的发件形式。费用和设置见 短信验证码，短号码见 短代码 SMS。

怎么拿到送达状态？

查询短信接口拿汇总，查询收件人接口拿每个号码的明细。读取时会从运营商刷新状态。Webhook 推送在规划中，目前支持的方式是轮询。

有哪些语言的示例？

API 文档 里有 curl、PHP、Python、Node.js、Java 的完整示例。它是普通的 REST + JSON 接口，任何 HTTP 客户端都能用，不需要安装 SDK。

最后核对：2026 年 10 月 24 日

相关指南： API 文档 · 短信验证码 · 短代码 SMS · 短信网关 · 马来西亚群发短信