mail

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites

前置条件

Before any mail operation, verify wallet readiness:

bash

npx awal@latest status              # must show authenticated
npx awal@latest balance --chain base  # need ≥ $1 USDC on Base

Not authenticated → run the
```
authenticate-wallet
```
skill
Insufficient funds → run the
```
fund
```
skill
No awal installed → direct user to https://docs.cdp.coinbase.com/agentic-wallet/welcome and
```
npx skills add coinbase/agentic-wallet-skills
```

在执行任何邮件操作前，请验证钱包状态：

bash

npx awal@latest status              # 必须显示已认证
npx awal@latest balance --chain base  # Base链上需持有≥1 USDC

未认证 → 运行
```
authenticate-wallet
```
技能
余额不足 → 运行
```
fund
```
技能
未安装awal → 引导用户访问https://docs.cdp.coinbase.com/agentic-wallet/welcome 并执行
```
npx skills add coinbase/agentic-wallet-skills
```

Workflow

工作流程

1. Determine mail type

1. 确定邮件类型

Ask the user: letter or postcard?

Type	Description
Letter	Printed document in an envelope. Supports color, double-sided, certified.
Postcard	4x6, 6x9, or 11x6. Always color, double-sided, standard class.

询问用户：选择信件还是明信片？

类型	说明
信件	装在信封中的打印文档。支持彩色、双面打印、挂号信服务。
明信片	尺寸可选4x6、6x9或11x6。默认彩色、双面打印，采用标准等级邮寄。

2. Gather content

2. 收集内容

Four content modes:

A. User provides PDF URL — pass directly in

pdf

field as URL string or

{ "download_url": "<url>" }

B. User provides local PDF file — read file, base64-encode, pass as

"data:application/pdf;base64,<data>"

C. User types a text message (auto-generate letter) — use the bulk endpoint with a single-row CSV. Wrap the user's message in a clean HTML letter template:

html

<html><body style="font-family:Georgia,serif;font-size:12pt;margin:1in;">
<p>[date]</p>
<p>[message body — preserve paragraphs]</p>
<p>[sender name]</p>
</body></html>

Set

content_mode: "html"

and

template_html

to the rendered HTML. See

references/postalform-api.md

§ Bulk (text auto-generation).

D. AI-generated postcard image — if the user wants a postcard but has no artwork, generate it using recraft-v3 via x402 ($0.04/image). The user just describes what they want — the agent handles all technical details automatically. See

references/image-generation.md

for the full flow.

Key rules the agent MUST follow:

Always use
```
"style":"digital_illustration"
```
in the request
Always append style modifiers to the user's prompt (see reference doc for exact suffix)
Never include words like "card", "postcard", "greeting card", "mockup" in the image prompt — these cause the model to generate a photo OF a card instead of the flat artwork
Auto-map postcard size to image dimensions: 4x6 → 1800x1200, 6x9 → 1800x1200, 11x6 → 2200x1200

Flow:

Transform user's prompt (strip card-related words, append style suffix)

Generate via

npx awal@latest x402 pay 'https://fal.x402.paysponge.com/fal-ai/recraft-v3' -X POST -d '<json>' --json

Poll
```
response_url
```
with
```
curl
```
until image URL is returned
Download image to a local file (e.g.
```
/tmp/postcard-artwork.webp
```
) and show it to the user
Ask the user to confirm: "Here's the generated artwork. Want to use this for your postcard, or would you like me to generate a new one?"
If the user wants a new image → go back to step 1 (re-generate costs another $0.04)
Once approved → convert to 2-page postcard PDF (Python + Pillow), base64-encode, pass to PostalForm

For postcards: PostalForm expects a 2-page PDF (page 1 = artwork, page 2 = mailing side). PostalForm fills addresses/indicia automatically — do NOT include addresses in the PDF.

提供四种内容模式：

A. 用户提供PDF链接 —— 直接在

pdf

字段中传入URL字符串或

{ "download_url": "<url>" }

。

B. 用户提供本地PDF文件 —— 读取文件，进行base64编码，格式为

"data:application/pdf;base64,<data>"

后传入。

C. 用户输入文本消息（自动生成信件） —— 使用批量接口，传入单行CSV。将用户消息嵌入简洁的HTML信件模板：

html

<html><body style="font-family:Georgia,serif;font-size:12pt;margin:1in;">
<p>[日期]</p>
<p>[消息内容 —— 保留段落格式]</p>
<p>[发件人姓名]</p>
</body></html>

设置

content_mode: "html"

，并将渲染后的HTML赋值给

template_html

。详情请参考

references/postalform-api.md

中的“批量（文本自动生成）”章节。

D. AI生成明信片图片 —— 如果用户需要明信片但没有素材，可通过x402支付（每张图片0.04美元）使用recraft-v3生成图片。用户只需描述需求，Agent会自动处理所有技术细节。完整流程请参考

references/image-generation.md

。

Agent必须遵循的关键规则：

请求中必须使用
```
"style":"digital_illustration"
```
必须在用户的提示词后追加风格修饰词（具体后缀请参考参考文档）
绝对不要在图片提示词中包含“卡片”“明信片”“贺卡”“模型”等词汇——这些会导致模型生成卡片的照片，而非平面插画
自动将明信片尺寸映射为图片分辨率：4x6 → 1800x1200，6x9 → 1800x1200，11x6 → 2200x1200

流程：

转换用户提示词（移除与卡片相关的词汇，追加风格后缀）

通过

npx awal@latest x402 pay 'https://fal.x402.paysponge.com/fal-ai/recraft-v3' -X POST -d '<json>' --json

生成图片

使用
```
curl
```
轮询
```
response_url
```
，直到获取图片URL
将图片下载到本地文件（例如
```
/tmp/postcard-artwork.webp
```
）并展示给用户
询问用户确认：“这是生成的插画。是否要用它制作明信片，还是需要重新生成？”
如果用户需要新图片 → 返回步骤1（重新生成需额外支付0.04美元）
确认后 → 将图片转换为2页的明信片PDF（使用Python + Pillow），进行base64编码后传入PostalForm

对于明信片：PostalForm要求传入2页PDF（第1页为插画，第2页为邮寄面）。PostalForm会自动填充地址/邮资标记——请勿在PDF中包含地址信息。

3. Get recipient

3. 获取收件人信息

List all files in the skill's local
```
data/
```
directory (e.g.
```
ls data/
```
) to see saved recipients. Recipient files are named
```
data/recipient_<firstname_lastname>.md
```
. Do NOT use glob patterns to search — always list the directory contents first, then match the user's recipient name against the filenames.
If a saved recipient matches, read that file to get the full address, then confirm: "Send to [Name] at [Address]?"
If no saved recipient matches: ask for full name, street address (line1, line2), city, state (2-letter), ZIP.
Always confirm the recipient name and address before proceeding.
After successful send, save new recipients to the skill's
```
data/
```
directory.

列出技能本地
```
data/
```
目录下的所有文件（例如
```
ls data/
```
），查看已保存的收件人。收件人文件命名为
```
data/recipient_<firstname_lastname>.md
```
。请勿使用通配符搜索——务必先列出目录内容，再将用户提供的收件人姓名与文件名匹配。
如果找到匹配的已保存收件人，读取该文件获取完整地址，然后确认：“是否寄给[姓名]，地址为[地址]？”
如果没有匹配的已保存收件人：询问用户的全名、街道地址（line1、line2）、城市、州（2字母缩写）、邮政编码。
务必在继续操作前确认收件人姓名和地址。
发送成功后，将新收件人信息保存到技能的
```
data/
```
目录中。

4. Get sender

4. 获取发件人信息

Read the skill's local
```
data/sender.md
```
directly to get the saved sender address. Do NOT use glob patterns — just read the file path.
If found: use it silently (no need to confirm each time).
If not found: ask for full sender name, email, and address. Save to the skill's
```
data/
```
directory after successful send.

直接读取技能本地的
```
data/sender.md
```
文件，获取已保存的发件人地址。请勿使用通配符——直接读取文件路径即可。
如果找到：直接使用（无需每次确认）。
如果未找到：询问用户的全名、邮箱和地址。发送成功后保存到技能的
```
data/
```
目录中。

5. Configure options (letters only)

5. 配置选项（仅适用于信件）

Option	Default	Values
`mail_class`	`"standard"`	`"standard"` , `"priority"` , `"express"`
`color`	`false`	`true` , `false`
`double_sided`	`true`	`true` , `false`
`certified`	`false`	`true` , `false`

Use defaults unless the user specifies otherwise. Postcards ignore these — always color, double-sided, standard, not certified.

选项	默认值	可选值
`mail_class`	`"standard"`	`"standard"` , `"priority"` , `"express"`
`color`	`false`	`true` , `false`
`double_sided`	`true`	`true` , `false`
`certified`	`false`	`true` , `false`

除非用户特别指定，否则使用默认值。明信片忽略这些选项——默认彩色、双面打印、标准等级、非挂号信。

6. Validate

6. 验证

Before payment, validate the order:

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders/validate' \
  -X POST -d '<json-body>' --json

If validation returns errors, fix and re-validate. Show validation errors to user in plain language.

支付前，请验证订单：

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders/validate' \
  -X POST -d '<json-body>' --json

如果验证返回错误，请修复后重新验证。用通俗易懂的语言将验证错误展示给用户。

7. Confirm and send

7. 确认并发送

Show a summary to the user:

Mail type:    Letter (standard, B&W)
To:           Jane Doe, 100 Main St, Springfield IL 62701
From:         [sender name + address]
Content:      [PDF URL or "auto-generated from your message"]
Est. cost:    ~$1-3 USDC (PostalForm sets price via x402)

Wait for user confirmation, then send:

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders' \
  -X POST -d '<json-body>' --json

向用户展示订单摘要：

邮件类型:    信件（标准等级，黑白）
收件人:      Jane Doe, 100 Main St, Springfield IL 62701
发件人:      [发件人姓名+地址]
内容:        [PDF链接或“根据您的消息自动生成”]
预估费用:    ~1-3 USDC（价格由PostalForm通过x402设定）

等待用户确认后，发送订单：

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders' \
  -X POST -d '<json-body>' --json

8. Track status

8. 跟踪状态

After a successful 202 response, extract

order_id

and poll:

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders/<order_id>' \
  -X GET --json

Report the current step to the user. No need to poll repeatedly — report the initial status and let the user know they can check again later.

收到成功的202响应后，提取

order_id

并轮询：

bash

npx awal@latest x402 pay 'https://postalform.com/api/machine/orders/<order_id>' \
  -X GET --json

将当前状态告知用户。无需持续轮询——只需告知初始状态，并说明用户可稍后再次查询。

9. Save addresses

9. 保存地址

After successful send, save addresses to the skill's

data/

directory (next to

SKILL.md

). This keeps addresses available across all projects and sessions where the skill is installed.

Save sender to
```
data/sender.md
```
if new (with name, email, full address)
Save recipient to
```
data/recipient_<firstname_lastname>.md
```
(with name and full address)

Format for

data/sender.md

markdown

Name: [name]
Email: [email]
Address: [line1], [line2], [city], [state] [zip]

Format for

data/recipient_<name>.md

markdown

Name: [full name]
Address: [line1], [line2], [city], [state] [zip]

发送成功后，将地址保存到技能的

data/

目录中（与

SKILL.md

同级）。这样在所有安装了该技能的项目和会话中都能使用这些地址。

如果是新发件人信息，保存到
```
data/sender.md
```
（包含姓名、邮箱、完整地址）
将收件人信息保存到
```
data/recipient_<firstname_lastname>.md
```
（包含姓名、完整地址）

data/sender.md

格式：

markdown

姓名: [姓名]
邮箱: [邮箱]
地址: [line1], [line2], [城市], [州] [邮政编码]

data/recipient_<name>.md

格式：

markdown

姓名: [全名]
地址: [line1], [line2], [城市], [州] [邮政编码]

x402 calling conventions

x402调用约定

PostalForm and fal.ai image generation both use x402 payment protocol via awal:

bash

undefined

PostalForm和fal.ai图片生成均通过awal使用x402支付协议：

bash

undefined

POST (orders / image generation)

POST（订单/图片生成）

npx awal@latest x402 pay '<url>' -X POST -d '<json-body>' --json

GET (status polling)

GET（状态轮询）

npx awal@latest x402 pay '<url>' -X GET --json


Rules:
- Single-quote JSON bodies and URLs to prevent shell expansion
- Do NOT pass `--max-amount`
- Output starts with a status line, then JSON — parse from first `{`
- Generate a fresh UUID v4 for each `request_id`
- fal.ai returns async results — poll the `response_url` with `curl` (no payment needed for polling)

npx awal@latest x402 pay '<url>' -X GET --json


规则：
- 对JSON请求体和URL使用单引号，避免Shell展开
- 请勿传入`--max-amount`参数
- 输出以状态行开头，随后是JSON——从第一个`{`开始解析
- 为每个`request_id`生成新的UUID v4
- fal.ai返回异步结果——使用`curl`轮询`response_url`（轮询无需支付）

Constraints

约束条件

Recipient must be in the US — PostalForm delivers to US addresses only. The sender/return address can be anywhere.
Single recipient per send — one letter or postcard per invocation.
Recipient state codes — must be 2-letter US abbreviation (e.g., CA, NY, IL).
Recipient ZIP codes — 5-digit or ZIP+4 format.
Sender address — can be any address worldwide. No US format restrictions on the return address.
Postcards — artwork PDF must not contain address/indicia data; PostalForm fills those automatically.
buyer_email
is required — PostalForm sends the payment receipt there.

收件人必须在美国境内——PostalForm仅支持美国地址投递。发件人/退回地址可位于任意地区。
每次发送仅限一位收件人——每次调用仅发送一封信件或一张明信片。
收件人州代码——必须为2字母的美国州缩写（例如CA、NY、IL）。
收件人邮政编码——5位或ZIP+4格式。
发件人地址——可位于全球任意地区。退回地址无美国格式限制。
明信片——插画PDF不得包含地址/邮资标记信息；PostalForm会自动填充这些内容。
buyer_email
为必填项——PostalForm会将支付收据发送至该邮箱。

Reference

参考资料

PostalForm endpoint payloads, address formats, and bulk auto-generation:
```
references/postalform-api.md
```
AI image generation models, payloads, and image-to-PDF conversion:
```
references/image-generation.md
```

PostalForm接口请求体、地址格式及批量自动生成：
```
references/postalform-api.md
```
AI图片生成模型、请求体及图片转PDF转换：
```
references/image-generation.md
```