API keys và webhooks

Mail Merge có REST API và webhooks gửi đi dành cho các nhà phát triển và người xây dựng không cần mã. Với khóa API, các tập lệnh của bạn có thể làm những gì ứng dụng web làm: đọc tài khoản, liệt kê mẫu và danh bạ, gửi chiến dịch và theo dõi người nhận của chúng. Với webhook, Mail Merge gọi điểm cuối của bạn ngay khi chiến dịch hoàn thành hoặc người nhận mở, nhấp, trả lời, bị trả lại hoặc hủy đăng ký, để CRM, bảng tính hoặc kênh Slack luôn cập nhật mà không cần thăm dò.

Cả hai đều nằm dưới Settings → Developers trong ứng dụng web và là một phần của gói Professional (xem Pricing). Nếu bạn muốn nói chuyện với Mail Merge từ một trợ lý AI thay vì viết mã, hãy sử dụng máy chủ MCP thay thế: nó hiển thị các tính năng tương tự dưới dạng công cụ, trên mọi gói.

Khóa API

Tạo khóa

Mở Settings → Developers → API keys và nhấp Create key.
Đặt tên nó theo nơi nó sẽ được sử dụng (Zapier, CRM sync), để bạn có thể thu hồi khóa đúng sau này.
Sao chép khóa. Nó chỉ được hiển thị một lần: Mail Merge chỉ giữ lại hàm băm của nó. Nếu bạn mất nó, hãy thu hồi nó và tạo một khóa mới.

Bạn có thể có tối đa 10 khóa trên mỗi tài khoản. Thu hồi khóa làm cho mọi yêu cầu được thực hiện với nó thất bại ngay lập tức; hàng sẽ biến mất khỏi danh sách.

Xác thực

Gửi khóa dưới dạng mã thông báo Bearer trên mọi yêu cầu, đối với URL cơ sở được hiển thị trên thẻ:

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Khóa hoạt động như tài khoản đã tạo nó, chính xác như một phiên đã đăng nhập: cùng một cấp phép Google, cùng một hạn ngạch hàng ngày, cùng các giới hạn gói. Không có “người dùng API” riêng biệt.

Điểm cuối

API là cùng một bề mặt /v1 mà ứng dụng web sử dụng, vì vậy bất cứ điều gì bạn có thể làm trên màn hình đều có một điểm cuối đằng sau nó. Những cái mà các tích hợp thường sử dụng nhất:

Gọi	Nó làm gì
`GET /v1/me`	Tài khoản: gói, hạn ngạch hàng ngày (tối đa, đã sử dụng, còn lại), múi giờ, siêu dữ liệu mẫu.
`GET /v1/templates` · `GET /v1/templates/{templateId}`	Các mẫu đã lưu của bạn; phần thân tải cho mỗi mẫu.
`GET /v1/contacts` · `POST /v1/contacts`	Sổ danh bạ (phân trang với `limit` / `cursor` → `nextCursor`).
`POST /v1/campaigns`	Gửi, lên lịch hoặc tự động hóa chiến dịch từ Google Sheet. Phần thân là cùng một phần mà trình xây dựng chiến dịch đăng: bảng tính, cột người nhận, chủ đề và nội dung với `{{merge tags}}`, và các tùy chọn gửi.
`GET /v1/campaigns` · `GET /v1/campaigns/{campaignId}/recipients`	Các chiến dịch của bạn và trạng thái của mỗi người nhận (đã gửi, đã đọc, đã nhấp, đã trả lời, bị trả lại, hủy đăng ký).
`POST /v1/campaigns/{campaignId}/status`	Tạm dừng, tiếp tục hoặc dừng chiến dịch đang chạy.
`POST /v1/recipients/verify`	Trình xác minh email.

Các phần thân yêu cầu và phản hồi là JSON. Bề mặt được nhập đầy đủ được tạo từ máy chủ dưới dạng tài liệu OpenAPI; liên hệ với chúng tôi nếu bạn cần lược đồ cho trình tạo máy khách.

Lỗi và giới hạn tốc độ

Các lỗi là trạng thái HTTP thực với một phong bì:

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

Trạng thái	`code`	Ý nghĩa
401		Khóa không xác định hoặc đã thu hồi, hoặc quyền truy cập Google của tài khoản cần kết nối lại.
403	`professional_plan_required`	Tài khoản của khóa không còn ở gói Professional. Các khóa không bị xóa khi hạ cấp; chúng hoạt động lại khi gói hoạt động.
429	`rate_limited`	Hơn 600 yêu cầu mỗi phút trên một khóa. Chờ một phút và thử lại.
400 / 404 / 409	`bad_request`, `not_found`, `conflict`, …	Bản thân yêu cầu, với thông báo nói cách sửa.

Giới hạn tốc độ được tính trên mỗi khóa trên mỗi phiên bản máy chủ API, vì vậy trần hiệu quả là “khoảng 600 mỗi phút”: không thiết kế xung quanh việc đạt được nó.

Webhooks

Thêm điểm cuối

Mở Settings → Developers → Webhooks và nhấp Add webhook.
Nhập URL HTTPS (plain http:// bị từ chối) và đánh dấu các sự kiện nó sẽ nhận.
Nhấp Send test trên hàng mới: Mail Merge đăng ping và thông báo cho bạn biết điểm cuối của bạn đã trả lời như thế nào.

Mỗi điểm cuối nhận được bí mật ký riêng của nó (whsec_…), được hiển thị trên hàng với nút sao chép. Bạn có thể có tối đa 5 điểm cuối trên mỗi tài khoản.

Sự kiện

Sự kiện	Khi nào	`data`
`campaign.completed`	Email cuối cùng của chiến dịch đã được xử lý.	`campaignId`, `name`, `status: "completed"`, `sentCount`, `campaignSize`
`campaign.paused` · `campaign.resumed` · `campaign.stopped`	Bạn tạm dừng, tiếp tục hoặc dừng chiến dịch.	`campaignId`, `name`, `status` (`paused` / `active` / `stopped`), `sentCount`
`email.opened`	Người nhận mở email, chỉ lần đầu tiên mỗi chiến dịch.	`campaignId`, `recipient`, `at`
`email.clicked`	Người nhận nhấp vào liên kết được theo dõi, mỗi lần nhấp.	`campaignId`, `recipient`, `at`, `url`
`email.replied`	Phát hiện trả lời trên luồng đã gửi.	`campaignId`, `recipient`, `at`
`email.bounced`	Phát hiện bị trả lại.	`campaignId`, `recipient`, `at`
`recipient.unsubscribed`	Người nhận sử dụng liên kết hủy đăng ký, chỉ lần đầu tiên mỗi chiến dịch.	`campaignId`, `recipient`, `at`, `method`

Các lần mở và nhấp cần theo dõi được bật cho chiến dịch; các trả lời và bị trả lại đến từ quét trả lời theo sau mỗi chiến dịch được gửi.

Giao hàng

Mail Merge gửi một POST cho mỗi sự kiện cho mỗi điểm cuối được đăng ký, với phần thân JSON:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

và ba tiêu đề:

Tiêu đề	Giá trị
`X-MailMerge-Event`	Tên sự kiện, giống như `event` trong phần thân.
`X-MailMerge-Delivery`	Id giao hàng, giống như `id`. Sử dụng nó để bỏ qua bản sao.
`X-MailMerge-Signature`	`sha256=` theo sau là HMAC-SHA256 thập lục phân của phần thân thô, được khóa bằng bí mật của điểm cuối.

Trả lời bằng bất kỳ 2xx nào trong 5 giây. Khi có lỗi mạng hoặc 5xx, Mail Merge thử lại một lần, sau 2 giây; 4xx được coi là phán quyết của bạn và không thử lại. Cùng một id giao hàng được gửi khi thử lại. Sau 20 lần giao hàng thất bại liên tiếp, điểm cuối sẽ bị vô hiệu hóa và hàng sẽ nói như vậy: sửa điểm cuối, sau đó xóa và thêm lại. Bất kỳ giao hàng thành công nào cũng đặt lại bộ đếm.

Các sự kiện được giao ít nhất một lần và không có thứ tự được đảm bảo. Các lần mở đặc biệt đến trong các đợt (mỗi ứng dụng mail hiển thị pixel theo dõi), vì vậy hãy làm cho trình xử lý của bạn idempotent trên X-MailMerge-Delivery hoặc trên (event, campaignId, recipient).

Xác minh chữ ký

Luôn xác minh trước khi tin tưởng tải trọng. Tính HMAC trên phần thân yêu cầu thô (các byte chính xác, trước khi phân tích JSON) và so sánh nó trong thời gian không đổi:

// Node.js (Express with `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier, Make và n8n

Không cần mã: tạo Catch Hook (Zapier Webhooks by Zapier), Custom webhook (Make) hoặc nút kích hoạt Webhook (n8n), dán URL nó cung cấp cho bạn làm điểm cuối, đánh dấu các sự kiện, và nhấp Send test để công cụ có thể lấy mẫu tải trọng. Các trường data trở thành các biến bạn ánh xạ vào bước tiếp theo (thêm hàng vào bảng tính, cập nhật liên hệ CRM, đăng vào Slack). Những công cụ đó không xác minh chữ ký theo mặc định; URL họ cung cấp cho bạn là không thể đoán được, đó là bảo vệ họ dựa vào.

Tiếp theo đi đâu

AI agents (MCP), nếu một trợ lý nên điều khiển Mail Merge cho bạn thay vì một tập lệnh.
Campaigns, để biết ý nghĩa của các trạng thái trong điểm cuối người nhận.
Pricing, để biết gói Professional bao gồm những gì.