什么是 UniOne Email API？

UniOne Email API 技能使 AI 智能体能够通过强大的 Web API 直接管理高成交量的邮件通信。该工具专为需要极高可靠性的开发人员和企业设计，支持每秒发送高达 3,000 封邮件，同时保持 99.88% 的送达率。对于需要自动化复杂消息工作流（从简单的通知到数据驱动的营销活动）的 Openclaw Skills 用户来说，这是一个至关重要的组件。

除了基础发送功能外，该技能还提供全面的基础设施管理。它处理域名验证、DKIM 和 SPF 验证以及抑制列表维护，以保护您的发件人声誉。通过集成此技能，您的智能体可以以编程方式确保发送的每封邮件都符合现代安全和送达标准。

下载入口:https://github.com/openclaw/skills/tree/main/skills/unione-repo/unione-api-skill

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

UniOne Email API 应用场景

• 部署用于订单确认、密码重置和账户警报的自动化事务性邮件。
• 利用动态个性化和自定义模板引擎管理大规模营销活动。
• 实时清理和验证邮件列表，以降低退信率并提高发件人权威性。
• 设置并验证带有 DKIM 和 SPF 记录的发件人域名，以确保进入收件箱。
• 通过 Webhooks 监控送达、打开和点击事件等参与度指标。

1. 该技能使用请求头中传递的安全 UNIONE_API_KEY 向 UniOne API 进行身份验证。
2. 在发送之前，智能体通过检索 DNS 记录值并验证 DKIM/SPF 状态来执行强制性的域名验证。
3. 邮件可以使用原始 HTML/文本或预配置模板撰写，支持 Velocity 或 Liquid 引擎。
4. 每次发送操作都利用幂等键，以防止在网络重试或失败期间出现重复消息。
5. 智能体针对 429 和 5xx 错误实施结构化重试策略（带有指数退避），以确保可靠投递。
6. 通过 Webhooks 管理实时跟踪，将事件数据推送到您的应用程序进行即时处理。

UniOne Email API 配置指南

要在您的 Openclaw Skills 环境中激活此技能，必须配置主 API 密钥：

# 设置您的 UniOne API Key
export UNIONE_API_KEY='your_api_key_here'

设置密钥后，第一个关键步骤是域名验证。使用 domain/get-dns-records.json 方法获取必要的 TXT 记录，并将其应用到您的 DNS 提供商（如 Cloudflare 或 Route53）。

UniOne Email API 数据架构与分类体系

该技能使用结构化 JSON 模式与 UniOne API 交互。以下是主要的数据对象：

name: unione
description: >
  Send transactional and marketing emails via UniOne Email API.
  Manage email templates, validate email addresses, check delivery statistics,
  manage suppression lists, configure webhooks, and handle domain settings.
  UniOne delivers billions of emails annually with 99.88% deliverability.
metadata:
  openclaw:
    emoji: "??"
    source: https://github.com/unione-repo/unione-api-skill
    homepage: https://unione.io/en/
    always: false
    requires:
      env:
        - UNIONE_API_KEY
    primaryEnv: UNIONE_API_KEY

UniOne Email API

UniOne is a transactional email service with Web API for sending transactional and marketing emails at scale (up to 3,000 emails/sec). This skill lets you send emails, manage templates, validate addresses, track delivery, and more.

Authentication

All requests require the UNIONE_API_KEY environment variable. Pass it as the X-API-KEY header.

Base URL: https://api.unione.io/en/transactional/api/v1/{method}.json?platform=openclaw

All methods use POST with JSON body.

CRITICAL: Domain Setup (Required Before Sending)

Emails will not be delivered until the sender's domain is verified. Before attempting to send any email, ensure the domain is set up:

Step 1: Get DNS Record Values — domain/get-dns-records.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/domain/get-dns-records.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"domain": "yourdomain.com"}'

API response returns raw values (not ready-to-paste DNS records):

{
  "status": "success",
  "domain": "yourdomain.com",
  "verification-record": "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661",
  "dkim": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"
}

The user must create 3 DNS TXT records from these values:

Present these 3 records clearly to the user and instruct them to add them at their DNS provider (Cloudflare, Route53, GoDaddy, etc.). The SPF record is always the same — it is not returned by the API.

Step 2: Verify Domain Ownership — domain/validate-verification.json

After the user has added DNS records:

curl -X POST "https://api.unione.io/en/transactional/api/v1/domain/validate-verification.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"domain": "yourdomain.com"}'

Step 3: Validate DKIM — domain/validate-dkim.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/domain/validate-dkim.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"domain": "yourdomain.com"}'

Step 4: List All Domains — domain/list.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/domain/list.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{}'

If domain verification fails: DNS propagation can take up to 48 hours. Suggest the user waits and retries, or checks their DNS records for typos.

Error Handling & Retry Policy

Retry Logic

When making API requests, implement exponential backoff for retryable errors:

Retryable errors (DO retry with exponential backoff):

Recommended retry schedule:

Non-retryable errors (do NOT retry):

Idempotency

For email/send.json, always include an idempotency_key to prevent duplicate sends during retries. This is critical for production systems.

The idempotency_key is a unique string (UUID recommended) passed in the request body. If UniOne receives two requests with the same key, the second request returns the result of the first without sending another email.

Always generate a unique idempotency key per logical send operation, and reuse the same key when retrying the same send.

1. Send Email — email/send.json

Send a transactional or marketing email to one or more recipients. Supports personalization via substitutions, templates, attachments, tracking, and metadata.

curl

curl -X POST "https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{
    "idempotency_key": "unique-uuid-here",
    "message": {
      "recipients": [
        {
          "email": "recipient@example.com",
          "substitutions": {
            "to_name": "John Smith"
          }
        }
      ],
      "body": {
        "html": "
Hello, {{to_name}}!
Your order has been confirmed.
",
        "plaintext": "Hello, {{to_name}}! Your order has been confirmed."
      },
      "subject": "Order Confirmation",
      "from_email": "noreply@yourdomain.com",
      "from_name": "Your Store"
    }
  }'

Node.js

const response = await fetch("https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.UNIONE_API_KEY
  },
  body: JSON.stringify({
    idempotency_key: crypto.randomUUID(),
    message: {
      recipients: [{ email: "recipient@example.com", substitutions: { to_name: "John" } }],
      body: {
        html: "
Hello, {{to_name}}!
Your order has been confirmed.
",
        plaintext: "Hello, {{to_name}}! Your order has been confirmed."
      },
      subject: "Order Confirmation",
      from_email: "noreply@yourdomain.com",
      from_name: "Your Store"
    }
  })
});
const data = await response.json();
// data.status === "success" → data.job_id, data.emails

Python

import requests, uuid, os

response = requests.post(
    "https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": os.environ["UNIONE_API_KEY"]
    },
    json={
        "idempotency_key": str(uuid.uuid4()),
        "message": {
            "recipients": [{"email": "recipient@example.com", "substitutions": {"to_name": "John"}}],
            "body": {
                "html": "
Hello, {{to_name}}!
Your order has been confirmed.
",
                "plaintext": "Hello, {{to_name}}! Your order has been confirmed."
            },
            "subject": "Order Confirmation",
            "from_email": "noreply@yourdomain.com",
            "from_name": "Your Store"
        }
    }
)
data = response.json()  # data["status"] == "success" → data["job_id"], data["emails"]

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "github.com/google/uuid"
)

func sendEmail() error {
    payload := map[string]interface{}{
        "idempotency_key": uuid.New().String(),
        "message": map[string]interface{}{
            "recipients": []map[string]interface{}{
                {"email": "recipient@example.com", "substitutions": map[string]string{"to_name": "John"}},
            },
            "body": map[string]string{
                "html":      "
Hello, {{to_name}}!
Your order has been confirmed.
",
                "plaintext": "Hello, {{to_name}}! Your order has been confirmed.",
            },
            "subject":    "Order Confirmation",
            "from_email": "noreply@yourdomain.com",
            "from_name":  "Your Store",
        },
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST",
        "https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw",
        bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-KEY", os.Getenv("UNIONE_API_KEY"))
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result) // result["status"] == "success"
    return nil
}

PHP

$ch = curl_init("https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-KEY: " . getenv("UNIONE_API_KEY")
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "idempotency_key" => bin2hex(random_bytes(16)),
        "message" => [
            "recipients" => [["email" => "recipient@example.com", "substitutions" => ["to_name" => "John"]]],
            "body" => [
                "html" => "
Hello, {{to_name}}!
Your order has been confirmed.
",
                "plaintext" => "Hello, {{to_name}}! Your order has been confirmed."
            ],
            "subject" => "Order Confirmation",
            "from_email" => "noreply@yourdomain.com",
            "from_name" => "Your Store"
        ]
    ])
]);
$response = curl_exec($ch);
$data = json_decode($response, true); // $data["status"] === "success"

Success response:

{
  "status": "success",
  "job_id": "1ZymBc-00041N-9X",
  "emails": ["recipient@example.com"]
}

Full parameters for message object:

*Not required if template_id is used.

Top-level parameter:

Send with template:

curl -X POST "https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{
    "idempotency_key": "unique-uuid-here",
    "message": {
      "recipients": [
        {
          "email": "customer@example.com",
          "substitutions": {
            "to_name": "Alice",
            "order_id": "ORD-12345",
            "total": "$59.99"
          }
        }
      ],
      "template_id": "your-template-id",
      "from_email": "shop@yourdomain.com",
      "from_name": "My Shop"
    }
  }'

Send to multiple recipients with personalization:

curl -X POST "https://api.unione.io/en/transactional/api/v1/email/send.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{
    "idempotency_key": "unique-uuid-here",
    "message": {
      "recipients": [
        {"email": "alice@example.com", "substitutions": {"to_name": "Alice"}},
        {"email": "bob@example.com", "substitutions": {"to_name": "Bob"}}
      ],
      "body": {
        "html": "
Hi {{to_name}}, check out our new {{promo_name}}!
"
      },
      "subject": "Special offer for you, {{to_name}}!",
      "from_email": "marketing@yourdomain.com",
      "from_name": "Marketing Team",
      "global_substitutions": {"promo_name": "Summer Sale"},
      "track_links": 1,
      "track_read": 1,
      "tags": ["promo", "summer-2026"]
    }
  }'

2. Email Validation — email-validation/single.json

Validate an email address to check if it exists and is deliverable.

curl -X POST "https://api.unione.io/en/transactional/api/v1/email-validation/single.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"email": "user@example.com"}'

Response:

{
  "status": "success",
  "email": "user@example.com",
  "result": "valid",
  "local_part": "user",
  "domain": "example.com",
  "mx_found": true,
  "mx_record": "mail.example.com"
}

Possible result values: "valid", "invalid", "unresolvable", "unknown".

3. Template Management

3.1 Create/Update Template — template/set.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/template/set.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{
    "template": {
      "name": "Order Confirmation",
      "subject": "Your order {{order_id}} is confirmed",
      "template_engine": "simple",
      "body": {
        "html": "
Thank you, {{to_name}}!
Order {{order_id}} total: {{total}}
",
        "plaintext": "Thank you, {{to_name}}! Order {{order_id}} total: {{total}}"
      },
      "from_email": "shop@yourdomain.com",
      "from_name": "My Shop"
    }
  }'

Response: {"status": "success", "template": {"id": "generated-template-id"}}

To update an existing template, include the "id" field in the template object.

3.2 Get Template — template/get.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/template/get.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"id": "template-id-here"}'

3.3 List Templates — template/list.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/template/list.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"limit": 50, "offset": 0}'

3.4 Delete Template — template/delete.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/template/delete.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"id": "template-id-here"}'

4. Webhook Management

Webhooks send real-time notifications about email events to your URL.

4.1 Set Webhook — webhook/set.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/webhook/set.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{
    "url": "https://yourapp.com/unione-webhook",
    "events": {
      "email_status": [
        "delivered", "opened", "clicked", "unsubscribed",
        "soft_bounced", "hard_bounced", "spam"
      ]
    }
  }'

4.2 List Webhooks — webhook/list.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/webhook/list.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{}'

4.3 Get / Delete Webhook — webhook/get.json / webhook/delete.json

# Get
curl -X POST ".../webhook/get.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"url": "https://yourapp.com/unione-webhook"}'

# Delete
curl -X POST ".../webhook/delete.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"url": "https://yourapp.com/unione-webhook"}'

5. Suppression List Management

5.1 Add — suppression/set.json

curl -X POST "https://api.unione.io/en/transactional/api/v1/suppression/set.json?platform=openclaw" r
  -H "Content-Type: application/json" r
  -H "X-API-KEY: $UNIONE_API_KEY" r
  -d '{"email": "user@example.com", "cause": "unsubscribed", "created": "2026-01-15 12:00:00"}'

Cause values: "unsubscribed", "temporary_unavailable", "permanent_unavailable", "complained".

5.2 Check — suppression/get.json

curl -X POST ".../suppression/get.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"email": "user@example.com"}'

5.3 List — suppression/list.json

curl -X POST ".../suppression/list.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"cause": "hard_bounced", "limit": 50, "offset": 0}'

5.4 Delete — suppression/delete.json

curl -X POST ".../suppression/delete.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"email": "user@example.com"}'

6. Event Dumps

6.1 Create — event-dump/create.json

curl -X POST ".../event-dump/create.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"start_time": "2026-01-01 00:00:00", "end_time": "2026-01-31 23:59:59", "limit": 50000, "all_events": true}'

6.2 Get / List / Delete

# Get dump status and download URL
curl -X POST ".../event-dump/get.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"dump_id": "dump-id"}'

# List all dumps
curl -X POST ".../event-dump/list.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{}'

# Delete a dump
curl -X POST ".../event-dump/delete.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"dump_id": "dump-id"}'

7. Tags — tag/list.json / tag/delete.json

# List tags
curl -X POST ".../tag/list.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{}'

# Delete tag
curl -X POST ".../tag/delete.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{"tag_id": 123}'

8. Projects — project/create.json / project/list.json

# Create project
curl -X POST ".../project/create.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"project": {"name": "My Project", "send_enabled": true}}'

# List projects
curl -X POST ".../project/list.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{}'

9. System Info — system/info.json

curl -X POST ".../system/info.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" -d '{}'

10. Subscribe (Double Opt-In) — email/subscribe.json

curl -X POST ".../email/subscribe.json?platform=openclaw" -H "X-API-KEY: $UNIONE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"from_email": "newsletter@yourdomain.com", "from_name": "Newsletter", "to_email": "newsubscriber@example.com"}'

Instructions for the Agent

1. Domain setup is mandatory. Before the first send, always check if the user's domain is verified. Run domain/list.json to check. If not verified, guide them through the domain setup process (Section: Domain Setup).
2. Always use api.unione.io as the API host for all requests.
3. Never send an email without explicit user confirmation. Always show the recipient, subject, and body summary before executing email/send.json. Wait for the user to approve. This applies to every send — including test emails and retries with new content.
4. Never modify or delete templates, webhooks, or suppressions without explicit user confirmation. Show what will be changed and wait for approval.
5. Always include idempotency_key in email/send.json requests. Generate a UUID for each unique send. Reuse the same key when retrying.
6. Implement retry logic for 429 and 5xx errors with exponential backoff (see Error Handling section). Never retry 400, 401, 403, 404, 413 errors.
7. For template operations, list available templates first before asking which one to use.
8. For validation, report the result clearly and suggest action.
9. Handle errors gracefully. If a request returns an error, explain what went wrong and suggest a fix.
10. Remind users that the from_email domain must be verified in their UniOne account.
11. Substitution syntax uses double curly braces: {{variable_name}}.
12. Attachments must be base64-encoded. Help the user encode files if needed.
13. Security: Never log or display the full API key. Remind users to keep their API key secret. Recommend using a least-privilege API key scoped to only the required actions.
14. DNS safety: When guiding users through domain DNS setup, instruct them to add records at their DNS provider themselves. Never ask users to paste private keys, certificates, or unrelated secrets into the conversation.
15. Code language: When the user's project uses a specific language (Node.js, Python, Go, PHP, etc.), provide code examples in that language. The examples in this skill can be adapted to any language that can make HTTP POST requests with JSON.
16. Scope: Only interact with UniOne API endpoints documented in this skill. Do not read unrelated files, environment variables, or access third-party services.

Common Workflows

"Send a test email"

1. Check domain verification (domain/list.json)
2. If domain not verified, guide through domain setup
3. Ask for recipient email address
4. Compose a simple test message
5. Confirm with user before sending
6. Execute email/send.json with idempotency_key
7. Report the job_id on success

"Check my deliverability setup"

1. Run system/info.json to get account status
2. Run domain/list.json to check domain verification
3. For each unverified domain, run domain/get-dns-records.json and show required records
4. Run domain/validate-dkim.json to check DKIM
5. Suggest fixes if domains are not fully verified

"Validate a list of emails"

1. For each email, call email-validation/single.json
2. Categorize results: valid, invalid, unknown
3. Report summary

"Set up delivery tracking"

1. Ask for webhook URL and events to track
2. Execute webhook/set.json
3. Confirm setup

Resources

• Full API Reference: https://docs.unione.io/en/web-api-ref
• Getting Started: https://docs.unione.io/en/
• Template Engines: https://docs.unione.io/en/web-api#section-template-engines
• Sign Up: https://cp.unione.io/en/user/registration/