pinme-email

用途

PinMe Email 用于在 PinMe 平台的项目（Worker TypeScript）中集成邮件发送功能。当 PinMe 项目需要发送邮件（send_email）时，该技能会指导 AI 生成符合平台规范的 Worker TypeScript 代码，帮助开发者正确调用 PinMe 平台的邮件发送 API。

主要能力

该技能围绕 PinMe Worker 环境下的邮件发送 API 调用展开，涵盖以下内容：

环境变量说明：Worker 创建时会自动注入环境变量，无需手动配置。
发送邮件 API 调用方式：包括接口地址、认证方式、发件人规则、请求格式与响应格式。
Worker 示例代码：提供 sendEmail 函数及在路由中使用的示例。
错误处理模式：说明 PinMe 平台 API 的统一响应格式，并提供推荐的统一错误处理函数 callPinmeAPI。
调用示例：展示如何在 Worker 中发起邮件发送调用并处理错误。

使用方式

环境变量

以下环境变量在 Worker 创建时自动注入，无需手动配置：

// backend/src/worker.ts
export interface Env {
  DB: D1Database;
  API_KEY: string;      // Project API Key — used for send_email authentication
  BASE_URL?: string;    // Optional override for PinMe API base URL, defaults to https://pinme.cloud
}

API_KEY 是 Worker 调用 PinMe 平台 API 的唯一凭证。当未设置 BASE_URL 时，默认值为 https://pinme.cloud。

发送邮件 API

接口地址：POST {BASE_URL}/api/v4/send_email
认证方式：X-API-Key 请求头（使用 env.API_KEY）
发件人：自动设置为 {project_name}@pinme.cloud

请求格式：

{
  "to": "user@example.com",
  "subject": "Your verification code",
  "html": "<p>Your code is <strong>123456</strong></p>"
}

字段说明：

字段	类型	是否必填	说明
to	string	是	收件人邮箱地址
subject	string	是	邮件主题
html	string	是	HTML 正文

响应格式：

成功（200）：

{ "code": 200, "msg": "ok", "data": { "ok": true } }

错误：

HTTP 状态码	含义	data.error 示例
401	API Key 缺失或无效	"X-API-Key header is required" / "Invalid API key"
400	参数校验失败	"Invalid email address" / "Subject is required"
500	邮件服务错误	"Failed to send email"

Worker 示例代码

async function sendEmail(env: Env, to: string, subject: string, html: string): Promise<{ ok: boolean; error?: string }> {
  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';
  const resp = await fetch(`${baseUrl}/api/v4/send_email`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': env.API_KEY,
    },
    body: JSON.stringify({ to, subject, html }),
  });

  const result = await resp.json() as { code: number; msg: string; data?: { ok?: boolean; error?: string } };

  if (resp.status !== 200 || result.code !== 200) {
    return { ok: false, error: result.data?.error || result.msg || 'Unknown error' };
  }
  return { ok: true };
}

// Usage in routes
async function handleSendVerification(request: Request, env: Env): Promise<Response> {
  const { email } = await request.json() as { email: string };
  const code = Math.random().toString().slice(2, 8);

  const result = await sendEmail(env, email, 'Verification Code',
    `<p>Your code is <strong>${code}</strong></p>`);

  if (!result.ok) {
    return json({ error: result.error }, 500);
  }
  return json({ ok: true });
}

错误处理模式

PinMe 平台 API 统一响应格式：

interface PinmeResponse<T = unknown> {
  code: number;   // 200=success, other=failure
  msg: string;    // "ok" | "error" | "invalid params"
  data?: T;       // Business data on success, may contain { error: string } on failure
}

推荐的统一错误处理函数：

async function callPinmeAPI<T>(url: string, apiKey: string, body: unknown): Promise<{ data?: T; error?: string }> {
  let resp: Response;
  try {
    resp = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
      body: JSON.stringify(body),
    });
  } catch {
    return { error: 'Network error' };
  }

  if (!resp.ok) {
    try {
      const err = await resp.json() as PinmeResponse;
      return { error: err.data && typeof err.data === 'object' && 'error' in err.data
        ? (err.data as { error: string }).error
        : err.msg || `HTTP ${resp.status}` };
    } catch {
      return { error: `HTTP ${resp.status}` };
    }
  }

  const result = await resp.json() as PinmeResponse<T>;
  if (result.code !== 200) {
    return { error: result.data && typeof result.data === 'object' && 'error' in result.data
      ? (result.data as { error: string }).error
      : result.msg };
  }
  return { data: result.data as T };
}

调用示例

const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';

// Send email
const emailResult = await callPinmeAPI<{ ok: boolean }>(
  `${baseUrl}/api/v4/send_email`, env.API_KEY,
  { to: 'user@example.com', subject: 'Hello', html: '<p>Hi</p>' },
);
if (emailResult.error) return json({ error: emailResult.error }, 500);

适用场景

需要在 PinMe Worker（TypeScript）项目中发送邮件的场景。
需要向 AI 提供规范，使其生成正确的 PinMe Worker 邮件发送代码。
需要参考 PinMe API 统一响应格式与错误处理方式的项目。

限制

资料未提供有关该技能的收费、价格、平台支持范围及其他使用限制的具体信息，相关内容暂未提供。