zeptomail

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zoho ZeptoMail

Use the ZeptoMail API via

curl

to send transactional emails like password resets, OTPs, welcome emails, and order confirmations.

Official docs:

https://www.zoho.com/zeptomail/help/api-home.html

通过

curl

调用ZeptoMail API发送事务性邮件，例如密码重置邮件、一次性验证码（OTP）、欢迎邮件和订单确认邮件。

官方文档：

https://www.zoho.com/zeptomail/help/api-home.html

When to Use

适用场景

Use this skill when you need to:

Send transactional emails (password resets, OTPs, confirmations)
Send templated emails with dynamic merge fields
Batch send to multiple recipients (up to 500)
Track email opens and clicks
Send emails with attachments or inline images

Note: ZeptoMail is for transactional emails only. For marketing/bulk emails, use Zoho Campaigns instead.

在以下场景中可使用该技能：

发送事务性邮件（密码重置、一次性验证码、确认邮件）
发送含动态合并字段的模板邮件
批量发送给多个收件人（最多500人）
追踪邮件的打开与点击情况
发送带附件或内嵌图片的邮件

注意： ZeptoMail仅适用于事务性邮件。如需发送营销/批量推广邮件，请使用Zoho Campaigns。

Prerequisites

前提条件

Sign up at Zoho ZeptoMail
Add and verify your domain
Create a Mail Agent and get your Send Mail Token

前往Zoho ZeptoMail注册账号
添加并验证你的域名
创建邮件代理（Mail Agent）并获取发送邮件令牌（Send Mail Token）

Get API Token

获取API令牌

Go to Mail Agents in ZeptoMail dashboard
Click on your Mail Agent
Go to SMTP & API tab
Copy the Send Mail Token

bash

export ZEPTOMAIL_API_KEY="your-send-mail-token"

进入ZeptoMail控制台的Mail Agents页面
点击你的邮件代理
切换到SMTP & API标签页
复制Send Mail Token

bash

export ZEPTOMAIL_API_KEY="your-send-mail-token"

Pricing

定价

Free tier: 10,000 emails
Paid: $2.50 per 10,000 emails

Important: When using
$VAR
in a command that pipes to another command, wrap the command containing
$VAR
in
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

免费套餐：10,000封邮件额度
付费套餐：每10,000封邮件2.50美元

重要提示： 当在包含管道符的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的bug，直接使用管道符时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

使用方法

Base URL:

https://api.zeptomail.com/v1.1

基础URL：

https://api.zeptomail.com/v1.1

1. Send Basic Email

1. 发送基础邮件

Write to

/tmp/zeptomail_request.json

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Welcome to Our Service",
  "htmlbody": "<h1>Welcome!</h1><p>Thank you for signing up.</p>"
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Welcome to Our Service",
  "htmlbody": "<h1>Welcome!</h1><p>Thank you for signing up.</p>"
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

2. Send Plain Text Email

2. 发送纯文本邮件

Write to

/tmp/zeptomail_request.json

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Your OTP Code",
  "textbody": "Your one-time password is: 123456\n\nThis code expires in 10 minutes."
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Your OTP Code",
  "textbody": "Your one-time password is: 123456\n\nThis code expires in 10 minutes."
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

3. Send Email with Tracking

3. 发送带追踪功能的邮件

Enable open and click tracking:

Write to

/tmp/zeptomail_request.json

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Order Confirmation #12345",
  "htmlbody": "<p>Your order has been confirmed. <a href=\"https://example.com/track\">Track your order</a></p>",
  "track_clicks": true,
  "track_opens": true,
  "client_reference": "order-12345"
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

开启打开与点击追踪：

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Order Confirmation #12345",
  "htmlbody": "<p>Your order has been confirmed. <a href=\"https://example.com/track\">Track your order</a></p>",
  "track_clicks": true,
  "track_opens": true,
  "client_reference": "order-12345"
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

4. Send to Multiple Recipients (CC/BCC)

4. 发送给多个收件人（抄送/密送）

Write to

/tmp/zeptomail_request.json

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      }
    }
  ],
  "cc": [
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      }
    }
  ],
  "bcc": [
    {
      "email_address": {
        "address": "admin@example.com",
        "name": "Admin"
      }
    }
  ],
  "subject": "Team Update",
  "htmlbody": "<p>Here is the latest update for the team.</p>",
  "reply_to": [
    {
      "address": "support@yourdomain.com",
      "name": "Support"
    }
  ]
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      }
    }
  ],
  "cc": [
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      }
    }
  ],
  "bcc": [
    {
      "email_address": {
        "address": "admin@example.com",
        "name": "Admin"
      }
    }
  ],
  "subject": "Team Update",
  "htmlbody": "<p>Here is the latest update for the team.</p>",
  "reply_to": [
    {
      "address": "support@yourdomain.com",
      "name": "Support"
    }
  ]
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

5. Send Email with Attachment (Base64)

5. 发送带附件的邮件（Base64编码）

bash

undefined

bash

undefined

Encode file to base64

将文件编码为Base64格式

FILE_CONTENT=$(base64 -i /path/to/file.pdf)


Write to `/tmp/zeptomail_request.json`:

```json
{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Your Invoice",
  "htmlbody": "<p>Please find your invoice attached.</p>",
  "attachments": [
    {
      "name": "invoice.pdf",
      "mime_type": "application/pdf",
      "content": "${FILE_CONTENT}"
    }
  ]
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

FILE_CONTENT=$(base64 -i /path/to/file.pdf)


编写内容到`/tmp/zeptomail_request.json`：

```json
{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Your Invoice",
  "htmlbody": "<p>Please find your invoice attached.</p>",
  "attachments": [
    {
      "name": "invoice.pdf",
      "mime_type": "application/pdf",
      "content": "${FILE_CONTENT}"
    }
  ]
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

6. Send Email with Inline Image

6. 发送带内嵌图片的邮件

bash

undefined

bash

undefined

Encode image to base64

将图片编码为Base64格式

IMAGE_CONTENT=$(base64 -i /path/to/logo.png)


Write to `/tmp/zeptomail_request.json`:

```json
{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Newsletter",
  "htmlbody": "<p><img src='cid:logo'/></p><p>Welcome to our newsletter!</p>",
  "inline_images": [
    {
      "cid": "logo",
      "name": "logo.png",
      "mime_type": "image/png",
      "content": "${IMAGE_CONTENT}"
    }
  ]
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

IMAGE_CONTENT=$(base64 -i /path/to/logo.png)


编写内容到`/tmp/zeptomail_request.json`：

```json
{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "subject": "Newsletter",
  "htmlbody": "<p><img src='cid:logo'/></p><p>Welcome to our newsletter!</p>",
  "inline_images": [
    {
      "cid": "logo",
      "name": "logo.png",
      "mime_type": "image/png",
      "content": "${IMAGE_CONTENT}"
    }
  ]
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

7. Send Templated Email

7. 发送模板邮件

Use pre-defined templates with merge fields:

Write to

/tmp/zeptomail_request.json

json

{
  "template_key": "your-template-key",
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "merge_info": {
    "user_name": "John",
    "order_id": "12345",
    "total": "$99.00"
  }
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/template" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

Template example (in ZeptoMail dashboard):

html

<p>Hi {{user_name}},</p>
<p>Your order #{{order_id}} totaling {{total}} has been shipped!</p>

使用预定义模板及合并字段：

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "template_key": "your-template-key",
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user@example.com",
        "name": "User"
      }
    }
  ],
  "merge_info": {
    "user_name": "John",
    "order_id": "12345",
    "total": "$99.00"
  }
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/template" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

模板示例（在ZeptoMail控制台中创建）：

html

<p>Hi {{user_name}},</p>
<p>Your order #{{order_id}} totaling {{total}} has been shipped!</p>

8. Batch Send (Multiple Recipients)

8. 批量发送（多个收件人）

Send to up to 500 recipients with personalized merge fields:

Write to

/tmp/zeptomail_request.json

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "subject": "Your Monthly Report - {{month}}",
  "htmlbody": "<p>Hi {{name}},</p><p>Here is your report for {{month}}.</p>",
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      },
      "merge_info": {
        "name": "Alice",
        "month": "December"
      }
    },
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      },
      "merge_info": {
        "name": "Bob",
        "month": "December"
      }
    }
  ]
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/batch" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

发送给最多500个收件人，并支持个性化合并字段：

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "subject": "Your Monthly Report - {{month}}",
  "htmlbody": "<p>Hi {{name}},</p><p>Here is your report for {{month}}.</p>",
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      },
      "merge_info": {
        "name": "Alice",
        "month": "December"
      }
    },
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      },
      "merge_info": {
        "name": "Bob",
        "month": "December"
      }
    }
  ]
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/batch" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

9. Batch Send with Template

9. 使用模板批量发送

Write to

/tmp/zeptomail_request.json

json

{
  "template_key": "your-template-key",
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      },
      "merge_info": {
        "user_name": "Alice",
        "code": "ABC123"
      }
    },
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      },
      "merge_info": {
        "user_name": "Bob",
        "code": "XYZ789"
      }
    }
  ]
}

Then run:

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/template/batch" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

编写内容到

/tmp/zeptomail_request.json

：

json

{
  "template_key": "your-template-key",
  "from": {
    "address": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "to": [
    {
      "email_address": {
        "address": "user1@example.com",
        "name": "User 1"
      },
      "merge_info": {
        "user_name": "Alice",
        "code": "ABC123"
      }
    },
    {
      "email_address": {
        "address": "user2@example.com",
        "name": "User 2"
      },
      "merge_info": {
        "user_name": "Bob",
        "code": "XYZ789"
      }
    }
  ]
}

然后执行：

bash

bash -c 'curl -s "https://api.zeptomail.com/v1.1/email/template/batch" -X POST --header "Authorization: Zoho-enczapikey ${ZEPTOMAIL_API_KEY}" --header "Content-Type: application/json" -d @/tmp/zeptomail_request.json'

Response Format

响应格式

Success Response

成功响应

json

{
  "data": [
  {
  "code": "EM_104",
  "additional_info": [],
  "message": "OK"
  }
  ],
  "message": "OK",
  "request_id": "abc123..."
}

json

{
  "data": [
  {
  "code": "EM_104",
  "additional_info": [],
  "message": "OK"
  }
  ],
  "message": "OK",
  "request_id": "abc123..."
}

Error Response

错误响应

json

{
  "error": {
  "code": "TM_102",
  "details": [
  {
  "code": "TM_102",
  "message": "Invalid email address",
  "target": "to"
  }
  ],
  "message": "Invalid request"
  },
  "request_id": "abc123..."
}

json

{
  "error": {
  "code": "TM_102",
  "details": [
  {
  "code": "TM_102",
  "message": "Invalid email address",
  "target": "to"
  }
  ],
  "message": "Invalid request"
  },
  "request_id": "abc123..."
}

Common Error Codes

常见错误码

Code	Description
TM_101	Authentication failed (invalid token)
TM_102	Invalid request parameters
TM_103	Domain not verified
TM_104	Rate limit exceeded
EM_104	Success

错误码	描述
TM_101	认证失败（令牌无效）
TM_102	请求参数无效
TM_103	域名未验证
TM_104	超出请求频率限制
EM_104	请求成功

Guidelines

使用规范

Transactional only - Do not use for marketing or bulk promotional emails
Verify domain first - Sender address must be from a verified domain
Size limit - Total email size (headers + body + attachments) must not exceed 15 MB
Batch limit - Maximum 500 recipients per batch request
Use templates - For consistent emails, create templates in the dashboard
Track reference - Use
```
client_reference
```
to correlate emails with your transactions
TLS required - API only supports TLS v1.2+

仅用于事务性邮件 - 请勿用于营销或批量推广邮件
先验证域名 - 发件人地址必须来自已验证的域名
大小限制 - 邮件总大小（头部+正文+附件）不得超过15 MB
批量限制 - 单次批量请求最多支持500个收件人
使用模板 - 如需发送格式统一的邮件，请在控制台创建模板
追踪关联 - 使用
```
client_reference
```
字段关联邮件与你的业务交易
要求TLS - API仅支持TLS v1.2及以上版本