Send SMS through your own HTTP API

This guide explains how to send the verification codes of Casdoor through an SMS gateway that has no built-in type. Casdoor calls an HTTP endpoint that you describe, so any SMS API that accepts a plain HTTP request works.

---

Learning outcomes

• Describe the HTTP request of your SMS gateway in Casdoor.
• Understand how Casdoor builds the request.

What you need

• An SMS gateway with an HTTP API
• Administrator access to the Casdoor admin console

---

Add the provider in Casdoor

1. In the Casdoor admin console, go to Identity > Providers and add a provider.

2. Set Category to SMS and Type to Custom HTTP SMS.

3. Fill in the fields:

   字段	含义	必需
   模板代码	消息模板。验证码会替换 %s 占位符（例如 Your code is %s）。留空则直接发送验证码本身。	不
   端点	短信接口地址。支持 {mobile} 和 {code} 占位符，会被替换为手机号和验证码。	是
   方法	HTTP 方法：GET、POST、PUT 或 DELETE。	是
   内容类型	非 GET 方法的请求体编码：application/x-www-form-urlencoded（默认）或 application/json。	不
   HTTP标头	额外的请求头（例如携带 API key 的 Authorization 头）。	不
   HTTP body映射	请求中 phoneNumber 和 content 所用的字段名（非 GET 方法）。	不
   参数	承载消息内容的字段名。优先于 HTTP body mapping 中的 content 值。	不
   启用代理	通过 Casdoor 配置的 SOCKS5 代理发送请求。见 概览。	不

4. Save the provider.

How Casdoor builds the request

• Content: The message is the Template code with %s replaced by the verification code. With an empty Template code, Casdoor sends the code alone.
• Field names: The phone number goes in the field phoneNumber, and the content goes in the field that Parameter names. You can rename both in HTTP body mapping. If Parameter is set, it takes precedence over a mapping of content.
• POST, PUT, and DELETE: Casdoor sends the phone number and the content in the body, in the selected Content type.
• GET: Casdoor appends the phone number and the content as query parameters. If the Endpoint contains the placeholder {mobile} or {code}, Casdoor fills in the placeholders and adds no query parameters.

Examples

A gateway that accepts a POST form with the fields to and text:

Field	Value
Endpoint	https://sms.example.com/api/send
Method	POST
Content type	application/x-www-form-urlencoded
HTTP header	Authorization: Bearer <your-token>
HTTP body mapping	phoneNumber to to
Parameter	text
Template code	Your verification code is %s

A gateway that takes everything in the URL with GET:

Field	Value
Endpoint	https://sms.example.com/send?mobile={mobile}&code={code}
Method	GET

Verify the result

Enter a phone number in SMS Test and send a test message.

See also

• SMS providers
• Custom HTTP notification provider