cloudflare-dns

通过 Cloudflare API 管理 DNS 记录。创建、列出、更新和删除 DNS 记录（A、AAAA、CNAME、TXT、MX、SPF、DKIM）。当代理需要添加或修改 DNS 记录、设置电子邮件身份验证 (SPF/DKIM/DMARC)、验证域或管理 Cloudflare 托管域上的任何 DNS 配置时使用。与 mailtarget-email 配合使用，可实现完全自主的发送域设置。

## 概述（中文）

通过 Cloudflare API 管理 DNS 记录。创建、列出、更新和删除 DNS 记录（A、AAAA、CNAME、TXT、MX、SPF、DKIM）。当代理需要添加或修改 DNS 记录、设置电子邮件身份验证 (SPF/DKIM/DMARC)、验证域或管理 Cloudflare 托管域上的任何 DNS 配置时使用。与 mailtarget-email 配合使用，可实现完全自主的发送域设置。

## 原文

# Cloudflare DNS

Manage DNS records on Cloudflare-hosted domains via the [Cloudflare API](https://developers.cloudflare.com/api/).

## Setup

Set these environment variables:

- `CLOUDFLARE_API_TOKEN` — API token with **DNS Write** permission ([create one](https://dash.cloudflare.com/profile/api-tokens))
- `CLOUDFLARE_ZONE_ID` — Zone ID of the domain (found on the domain overview page in Cloudflare dashboard)

## API Basics

Base URL: `https://api.cloudflare.com/client/v4`

Auth header: `Authorization: Bearer $CLOUDFLARE_API_TOKEN`

All responses follow: `{"success": true, "result": {...}, "errors": [], "messages": []}`

## Common Operations

### List DNS records

```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.result[] | {id, type, name, content}'
```

Filter by type or name:
```bash
# TXT records only
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records?type=TXT" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# By name
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records?name=example.com" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

### Create a DNS record

```bash
curl -X POST "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TXT",
    "name": "example.com",
    "content": "v=spf1 include:_spf.mailtarget.co ~all",
    "ttl": 3600
  }'
```

### Update a DNS record

```bash
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records/$RECORD_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "new-value"}'
```

### Delete a DNS record

```bash
curl -X DELETE "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records/$RECORD_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

## Email Authentication Setup

### SPF record (TXT)

```json
{"type": "TXT", "name": "example.com", "content": "v=spf1 include:_spf.mailtarget.co ~all", "ttl": 3600}
```

If an SPF record already exists, merge the `include:` directive into the existing value.

### DKIM record (TXT)

Use the hostname and value from your email provider:

```json
{"type": "TXT", "name": "selector._domainkey.example.com", "content": "v=DKIM1; k=rsa; p=MIGf...", "ttl": 3600}
```

### DMARC record (TXT)

```json
{"type": "TXT", "name": "_dmarc.example.com", "content": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com", "ttl": 3600}
```

### CNAME record (for tracking domains)

```json
{"type": "CNAME", "name": "track.example.com", "content": "tracking.mailtarget.co", "ttl": 3600, "proxied": false}
```

**Important:** Set `proxied: false` for email-related CNAME records (DKIM, tracking) — Cloudflare proxy breaks email authentication.

## Mailtarget Integration Workflow

When used together with `mailtarget-email`, the agent can do end-to-end domain setup:

1. **Create sending domain** in Mailtarget → `POST /domain/sending`
2. **Read required DNS records** → `GET /domain/sending/{id}` returns SPF, DKIM, CNAME values
3. **Add DNS records** in Cloudflare using this skill
4. **Verify domain** in Mailtarget → `PUT /domain/sending/{id}/verify-txt`
5. **Confirm** all records are verified

Zero manual DNS editing required.

## Reference

See [references/api.md](references/api.md) for full endpoint documentation.