full/wiki/api/07-sender.md

# SENDER API

邮件、短信发送及验证码校验。

> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。

## 接入方式

- 动态 HTTP：`POST /rpc/sender/{Service}/{Method}`
- 原生 gRPC：`/sender.{Service}/{Method}`
- grpc-gateway：`POST /sender.{Service}/{Method}`
- 鉴权：需要登录的接口通过 `Authorization: <JWT>` 传递裸 JWT，不添加 `Bearer` 前缀。
- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。

## 服务概览

| 服务 | 方法数 | 说明 |
|---|---:|---|
| `Mail` | 1 | Mail 服务 |
| `Sms` | 2 | Sms 服务 |

## Mail

| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|---|---|---|---|---|
| `Send` | `POST /rpc/sender/Mail/Send` | [`sender.SendMailRequest`](#sendersendmailrequest) | [`sender.SendMailReply`](#sendersendmailreply) | Unary |

### Mail.Send

- 动态 HTTP：`POST /rpc/sender/Mail/Send`
- gRPC：`/sender.Mail/Send`
- 请求示例：

```json
{
  "isGenCode": false,
  "paramters": {
    "key": "string"
  },
  "provider": "string",
  "templateKey": "string",
  "to": "string"
}
```

## Sms

| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|---|---|---|---|---|
| `Send` | `POST /rpc/sender/Sms/Send` | [`sender.SmsSendRequest`](#sendersmssendrequest) | [`sender.SmsReply`](#sendersmsreply) | Unary |
| `Verify` | `POST /rpc/sender/Sms/Verify` | [`sender.SmsVerifyRequest`](#sendersmsverifyrequest) | [`sender.SmsReply`](#sendersmsreply) | Unary |

### Sms.Send

- 动态 HTTP：`POST /rpc/sender/Sms/Send`
- gRPC：`/sender.Sms/Send`
- 请求示例：

```json
{
  "isGenCode": false,
  "paramters": {
    "key": "string"
  },
  "phone": "string",
  "provider": "string",
  "signName": "string",
  "templateCode": "string"
}
```

### Sms.Verify

- 动态 HTTP：`POST /rpc/sender/Sms/Verify`
- gRPC：`/sender.Sms/Verify`
- 请求示例：

```json
{
  "code": "string",
  "phone": "string"
}
```

## 消息结构

### sender.SendMailReply

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `data` | `string` | 可选 |

### sender.SendMailRequest

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `provider` | `string` | 可选 |
| `templateKey` | `string` | 可选 |
| `to` | `string` | 可选 |
| `isGenCode` | `bool` | 可选 |
| `paramters` | `map<string, string>` | 对象映射 |

### sender.SendMailRequest.ParamtersEntry

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `key` | `string` | 可选 |
| `value` | `string` | 可选 |

### sender.SmsReply

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `reply` | `string` | 可选 |

### sender.SmsSendRequest

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `provider` | `string` | 可选 |
| `signName` | `string` | 可选 |
| `templateCode` | `string` | 可选 |
| `phone` | `string` | 可选 |
| `isGenCode` | `bool` | 可选 |
| `paramters` | `map<string, string>` | 对象映射 |

### sender.SmsSendRequest.ParamtersEntry

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `key` | `string` | 可选 |
| `value` | `string` | 可选 |

### sender.SmsVerifyRequest

| JSON 字段 | 类型 | 规则 |
|---|---|---|
| `phone` | `string` | 可选 |
| `code` | `string` | 可选 |