storlead-sasa-platform/deploy/master/mkt_mail_message_insert_doc.json

{
  "table": "mkt_mail_message",
  "purpose": "通过 SQL 直接插入营销邮件，由定时任务 DelaySendEmailTaskJob / sendDueDelayedMails 扫描发送",
  "scene": "定时发送 + 可选打开追踪",
  "db_not_null": ["account_id", "recipient"],
  "business_required_for_delay_send": {
    "description": "要被定时任务捞到并成功发出，除库表 NOT NULL 外还需满足下列条件",
    "fields": [
      {
        "name": "account_id",
        "required": true,
        "note": "smtp_pop_settings.id，且 scene=MKT、enabled=1、密码可解密"
      },
      {
        "name": "recipient",
        "required": true,
        "note": "收件人邮箱，单人一行"
      },
      {
        "name": "subject",
        "required": true,
        "note": "主题；发送组 MIME 时会用到，建议必填"
      },
      {
        "name": "content",
        "required": true,
        "note": "HTML 正文；像素在真正 SMTP 发送时注入，不必在 content 里手写"
      },
      {
        "name": "status",
        "required": true,
        "value": -1,
        "note": "必须为 -1（待定时发送），任务只扫 status=-1"
      },
      {
        "name": "delay_send_time",
        "required": true,
        "note": "定时发送时间；任务条件 delay_send_time <= now()"
      },
      {
        "name": "folder",
        "required": true,
        "recommended": "SENTING",
        "note": "发件中；与系统发信路径一致"
      },
      {
        "name": "in_out_mark",
        "required": true,
        "recommended": 2,
        "note": "2=发件"
      },
      {
        "name": "is_delete",
        "required": true,
        "value": 0,
        "note": "必须为 0，任务会过滤已删除"
      },
      {
        "name": "is_track",
        "required_if_open_track": true,
        "value": 1,
        "note": "需要打开追踪时填 1；发送时若无 track_token 会自动生成并注入像素"
      }
    ]
  },
  "optional_on_insert": {
    "track_token": "可不填；is_track=1 时由发送前 prepareTrackBeforeSend 自动生成",
    "from_addr": "建议填账户邮箱；不填则仅依赖 SMTP 账户 From",
    "from_name": "建议填发件显示名",
    "biz_ref": "业务单号，便于回查/open_stats",
    "biz_batch_no": "批次号",
    "org_id": "组织 ID",
    "owner_by": "归属人",
    "create_by": "创建人",
    "mkt_mail_status": "可不插；发送前 ensureStatus 会补状态行"
  },
  "status_enum": {
    "-2": "草稿",
    "-1": "待定时发送（SQL 插库走定时任务请用此值）",
    "0": "发送中",
    "1": "发送成功",
    "2": "发送失败"
  },
  "fields": [
    {
      "name": "id",
      "type": "bigint",
      "nullable": false,
      "default": "AUTO_INCREMENT",
      "desc": "主键，勿手填"
    },
    {
      "name": "account_id",
      "type": "bigint",
      "nullable": false,
      "default": null,
      "desc": "发信账户 ID → smtp_pop_settings.id（scene=MKT）"
    },
    {
      "name": "org_id",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "组织 ID"
    },
    {
      "name": "biz_ref",
      "type": "varchar(64)",
      "nullable": true,
      "default": null,
      "desc": "调用方业务单号"
    },
    {
      "name": "biz_batch_no",
      "type": "varchar(64)",
      "nullable": true,
      "default": null,
      "desc": "批量批次号"
    },
    {
      "name": "message_id",
      "type": "varchar(255)",
      "nullable": true,
      "default": null,
      "desc": "SMTP Message-ID，发送成功后系统回写，插库勿填"
    },
    {
      "name": "track_token",
      "type": "varchar(64)",
      "nullable": true,
      "default": null,
      "desc": "打开追踪 token；is_track=1 时可空，发送前自动生成；唯一索引"
    },
    {
      "name": "subject",
      "type": "varchar(512)",
      "nullable": true,
      "default": null,
      "desc": "主题（业务上必填）"
    },
    {
      "name": "from_addr",
      "type": "varchar(255)",
      "nullable": true,
      "default": null,
      "desc": "发件人地址"
    },
    {
      "name": "from_name",
      "type": "varchar(255)",
      "nullable": true,
      "default": null,
      "desc": "发件人显示名"
    },
    {
      "name": "recipient",
      "type": "varchar(512)",
      "nullable": false,
      "default": null,
      "desc": "收件人邮箱"
    },
    {
      "name": "recipient_cc",
      "type": "text",
      "nullable": true,
      "default": null,
      "desc": "抄送，逗号分隔"
    },
    {
      "name": "recipient_bcc",
      "type": "text",
      "nullable": true,
      "default": null,
      "desc": "密送，逗号分隔"
    },
    {
      "name": "content",
      "type": "mediumtext",
      "nullable": true,
      "default": null,
      "desc": "正文 HTML（业务上必填）"
    },
    {
      "name": "folder",
      "type": "varchar(32)",
      "nullable": true,
      "default": null,
      "desc": "INBOX/SENT/SENTING/DRAFT；定时发信建议 SENTING"
    },
    {
      "name": "msg_uid",
      "type": "varchar(128)",
      "nullable": true,
      "default": null,
      "desc": "服务器 UID，发信插库勿填"
    },
    {
      "name": "recipient_date",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "收信时间，发信插库勿填"
    },
    {
      "name": "sent_date",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "邮件头 SentDate，一般系统回写"
    },
    {
      "name": "is_only_head",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "是否仅拉头"
    },
    {
      "name": "is_read",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "是否已读（本地）"
    },
    {
      "name": "in_out_mark",
      "type": "tinyint",
      "nullable": true,
      "default": null,
      "desc": "1收件 2发件；定时发信填 2"
    },
    {
      "name": "email_size",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "邮件大小"
    },
    {
      "name": "in_reply_to",
      "type": "varchar(512)",
      "nullable": true,
      "default": null,
      "desc": "In-Reply-To，发信插库一般为空"
    },
    {
      "name": "reply_msg_id",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "回复的原邮件 ID"
    },
    {
      "name": "status",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "投递状态；定时任务请显式写 -1（默认 0 是发送中，不会被定时任务扫描）"
    },
    {
      "name": "fail_reason",
      "type": "varchar(512)",
      "nullable": true,
      "default": null,
      "desc": "失败原因，插库勿填"
    },
    {
      "name": "is_track",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "是否打开追踪；需要像素填 1"
    },
    {
      "name": "opened",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "是否已打开，插库保持 0"
    },
    {
      "name": "first_open_time",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "首次打开时间"
    },
    {
      "name": "open_count",
      "type": "int",
      "nullable": false,
      "default": 0,
      "desc": "打开次数"
    },
    {
      "name": "sent_time",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "SMTP 成功时间，系统回写"
    },
    {
      "name": "delay_send_time",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "定时发送时间；status=-1 时必填"
    },
    {
      "name": "owner_by",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "数据归属人"
    },
    {
      "name": "create_by",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "创建人"
    },
    {
      "name": "update_by",
      "type": "bigint",
      "nullable": true,
      "default": null,
      "desc": "更新人"
    },
    {
      "name": "create_time",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "创建时间，建议 NOW()"
    },
    {
      "name": "update_time",
      "type": "datetime",
      "nullable": true,
      "default": null,
      "desc": "更新时间，建议 NOW()"
    },
    {
      "name": "is_delete",
      "type": "tinyint",
      "nullable": false,
      "default": 0,
      "desc": "逻辑删除；必须 0"
    },
    {
      "name": "enabled",
      "type": "tinyint",
      "nullable": false,
      "default": 1,
      "desc": "是否启用"
    },
    {
      "name": "sort",
      "type": "int",
      "nullable": true,
      "default": null,
      "desc": "排序"
    }
  ],
  "example_insert_sql": "INSERT INTO mkt_mail_message (\n  account_id, org_id, biz_ref, biz_batch_no,\n  subject, from_addr, from_name, recipient, content,\n  folder, in_out_mark, status, delay_send_time, is_track,\n  owner_by, create_by, create_time, update_time, is_delete, enabled\n) VALUES (\n  1001, NULL, 'ACT-20260814-001', 'BATCH-01',\n  '促销活动', 'mkt@example.com', '营销号', 'user@example.com', '<html><body><p>你好</p></body></html>',\n  'SENTING', 2, -1, '2026-08-14 12:00:00', 1,\n  1, 1, NOW(), NOW(), 0, 1\n);",
  "example_row_json": {
    "account_id": 1001,
    "biz_ref": "ACT-20260814-001",
    "biz_batch_no": "BATCH-01",
    "subject": "促销活动",
    "from_addr": "mkt@example.com",
    "from_name": "营销号",
    "recipient": "user@example.com",
    "content": "<html><body><p>你好</p></body></html>",
    "folder": "SENTING",
    "in_out_mark": 2,
    "status": -1,
    "delay_send_time": "2026-08-14 12:00:00",
    "is_track": 1,
    "track_token": null,
    "opened": 0,
    "open_count": 0,
    "is_delete": 0,
    "enabled": 1,
    "owner_by": 1,
    "create_by": 1
  },
  "notes": [
    "定时任务扫描条件：is_delete=0 AND status=-1 AND delay_send_time IS NOT NULL AND delay_send_time<=NOW()",
    "status 表默认是 0（发送中），SQL 插定时邮件必须显式写 status=-1",
    "is_track=1 时可不写 track_token；真正 SMTP 发送前会自动生成并注入像素",
    "像素依赖配置 storlead.mail.track-base-url（公网可达，含 context-path）",
    "mkt_mail_status 可不插；发送链路会 ensureStatus；打开/回复/发送结果会回写该表"
  ]
}