Tạo và quản lý API Key của bạn

Published: 16 tháng 7, 2026 · Last updated: 21 tháng 7, 2026 · By Marcus Biel

Trang API Key cung cấp cho hệ thống bên ngoài quyền truy cập đã xác thực vào các endpoint API Maildroppa được hỗ trợ trong tài khoản của bạn.

Bạn có thể tạo một API key, sao chép toàn bộ giá trị bí mật của key, đặt lại an toàn bằng cách xoay vòng key hoặc xóa key khi không còn cần thiết. Cùng một account key có thể được sử dụng bởi các tích hợp phía máy chủ và các trình kích hoạt yêu cầu API trong Maildroppa Automations.

API key đại diện cho tài khoản Maildroppa của bạn. Hãy bảo vệ key như mật khẩu: bất kỳ ai có được key đều có thể gọi các endpoint API mà key đó được phép sử dụng cho đến khi bạn xoay vòng hoặc xóa key.

API Key dùng để làm gì

Sử dụng API key khi phần mềm bên ngoài Maildroppa cần làm việc với Maildroppa mà không cần người dùng đăng nhập tương tác.

Các ví dụ điển hình gồm:

• Đồng bộ hóa subscriber với CRM, cửa hàng, hệ thống thành viên hoặc cơ sở dữ liệu nội bộ.
• Tạo hoặc cập nhật subscriber từ ứng dụng phía máy chủ.
• Đọc hoặc quản lý tag, field, giá trị field và segment thông qua các endpoint được hỗ trợ.
• Gửi sự kiện tùy chỉnh đến trình kích hoạt yêu cầu API trong một Automation.
• Gửi Email Message giao dịch thông qua API.
• Quản lý các webhook subscription dựa trên API.

API key dành cho giao tiếp giữa máy chủ với máy chủ. Key không dành cho mã chạy trong trình duyệt của khách truy cập, website công khai, ứng dụng di động hoặc biểu mẫu đăng ký được nhúng.

Trang hiện được đánh dấu là “beta”. Hãy sử dụng tài liệu OpenAPI được liên kết làm nguồn thông tin về các endpoint, request body, tham số và response schema hiện được API hỗ trợ.

Mở trang API Key

Mở “Settings”, mở rộng “Developers” và chọn “API key”.

Bạn cũng có thể mở trực tiếp trang này tại:

https://app.maildroppa.com/settings/developers/api-key

Trang này bao gồm:

• Bảng API key có huy hiệu beta.
• Liên kết “View OpenAPI docs”.
• Trạng thái trống và nút “Create API key” khi chưa có key.
• Biểu diễn được che của key hiện tại khi đã có key.
• Nút “Copy” để sao chép toàn bộ key.
• Các thao tác “Rotate API key” và “Delete API key” để thay thế hoặc xóa key hiện tại.

Maildroppa cho phép một API key cho mỗi tài khoản. Trang này không tạo các key riêng cho từng ứng dụng, môi trường hoặc thành viên nhóm.

Tạo API Key

Khi trang hiển thị “No API key yet”, hãy nhấp vào “Create API key”.

Maildroppa tạo key ngay lập tức. Không có hộp thoại xác nhận cho lần tạo đầu tiên này. Trong khi yêu cầu đang được xử lý, nút chuyển thành “Creating API key” và trang tạm thời vô hiệu hóa các thao tác key khác.

Sau khi key được tạo:

• Trạng thái trống biến mất.
• Một key được che xuất hiện.
• Các thao tác “Copy”, “Rotate API key” và “Delete API key” khả dụng.
• Maildroppa hiển thị thông báo thành công “API key updated”.

Nếu tài khoản đã có một key khác, Maildroppa không tạo key thứ hai. Hãy sử dụng key hiện có hoặc xoay vòng key đó.

Tìm hiểu về Key được che

Trang không hiển thị toàn bộ bí mật dưới dạng văn bản thông thường. Trang hiển thị năm ký tự đầu tiên, theo sau là năm dấu hoa thị, ví dụ:

a1b2c*****

Đây chỉ là lớp che trực quan. Các dấu hoa thị không đại diện cho độ dài thực của key và giá trị được che không thể dùng cho yêu cầu API.

Nhấp vào “Copy” để ghi toàn bộ key hiện tại vào clipboard. Sau khi sao chép thành công, nút sẽ tạm thời đổi thành “Copied!”.

Key vẫn được che khi bạn quay lại trang, nhưng “Copy” vẫn tiếp tục sao chép toàn bộ giá trị hiện tại. Vì vậy, bạn không cần xoay vòng một key hợp lệ chỉ vì chưa lưu key trong lúc tạo.

Lưu trữ Key an toàn

Đưa key đã sao chép trực tiếp vào kho lưu trữ bí mật mà tích hợp sử dụng.

Các vị trí phù hợp gồm:

• Trình quản lý secret được quản lý.
• Cấu hình môi trường máy chủ được bảo vệ.
• Secret triển khai được mã hóa.
• Trình quản lý mật khẩu dùng cho khôi phục vận hành.

Không lưu key trong:

• JavaScript phía trình duyệt hoặc bundle frontend khác có thể tải xuống.
• Tệp mã nguồn công khai hoặc riêng tư đã commit vào repository.
• URL hoặc query parameter.
• Tài liệu công khai, ảnh chụp màn hình, tin nhắn hỗ trợ hoặc trình theo dõi issue.
• Log ứng dụng dùng chung, sự kiện phân tích hoặc báo cáo lỗi.
• Bảng tính không mã hóa hoặc cuộc trò chuyện nhóm thông thường.

Không thêm key vào ví dụ curl sẽ được sao chép vào tài liệu hoặc lịch sử shell được chia sẻ với người khác. Ưu tiên sử dụng biến môi trường như MAILDROPPA_API_KEY.

Sử dụng API Key

Gửi toàn bộ key trong HTTP request header X-API-Key:

X-API-Key: your-complete-api-key

Không gửi key dưới dạng Bearer token. Maildroppa yêu cầu X-API-Key, không phải Authorization: Bearer ....

API production và tài liệu OpenAPI tương tác có tại:

https://api.maildroppa.com

Nhấp vào “View OpenAPI docs” trên trang API Key để mở tài liệu trong tab trình duyệt mới. Chọn một endpoint tại đó để xem method, path, tham số, request body, response type và các status code có thể có.

Ví dụ yêu cầu

Ví dụ sau truy xuất trang đầu tiên của subscriber. Ví dụ đọc key từ biến môi trường thay vì đặt trực tiếp secret vào lệnh:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Thiết lập biến trong môi trường bảo mật nơi tích hợp chạy. Method, path, query parameter và body cụ thể phụ thuộc vào endpoint. Hãy sao chép các chi tiết đó từ tài liệu OpenAPI thay vì đoán dựa trên các thao tác có sẵn trong ứng dụng Maildroppa.

Yêu cầu có JSON Body

Đối với yêu cầu gửi JSON, hãy thêm:

Content-Type: application/json

Ví dụ, cấu trúc cơ bản là:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint và body của nó là các placeholder. Hãy thay thế chúng bằng endpoint được tài liệu hóa và request schema tương ứng.

Key có thể truy cập gì

Key chỉ hoạt động với các endpoint hỗ trợ xác thực bằng API key. Một trang hoặc yêu cầu được ứng dụng Maildroppa sử dụng nội bộ không tự động trở thành một phần của customer API công khai.

Tài liệu OpenAPI hiển thị customer API được hỗ trợ. Nếu một path không được tài liệu hóa để sử dụng API key, đừng giả định rằng key có thể truy cập path đó.

Trang API Key không cung cấp scope hoặc checkbox quyền theo từng endpoint. Vì vậy, key hiện tại của tài khoản cần được xử lý như một thông tin xác thực có giá trị cao, ngay cả khi một tích hợp chỉ sử dụng một endpoint duy nhất.

Giới hạn tốc độ

Hợp đồng OpenAPI hiện tại ghi nhận các giới hạn API key sau:

• Customer API mặc định: 300 yêu cầu mỗi phút và 2.000 yêu cầu mỗi giờ.
• Events API tại /events: 100 yêu cầu mỗi giây với khả năng burst 500 yêu cầu.

Các giới hạn này được áp dụng cho tài khoản Maildroppa, không độc lập cho từng script dùng chung key. Vì vậy, nhiều tích hợp có thể cùng tiêu thụ một hạn mức.

Khi Maildroppa trả về 429 Too Many Requests, hãy ngừng gửi yêu cầu mới và tuân thủ response header Retry-After nếu có. Sử dụng hàng đợi và backoff có kiểm soát thay vì khởi chạy nhiều lần thử lại song song.

Chính sách giới hạn tốc độ có thể thay đổi trong thời gian API còn beta. Hãy kiểm tra thông tin ở đầu tài liệu OpenAPI trước khi thiết kế các tích hợp có lưu lượng lớn.

Sử dụng Key cho các yêu cầu API của Automation

Một Automation có thể bắt đầu khi hệ thống của bạn gửi sự kiện tùy chỉnh đến Events API của Maildroppa.

Khi bạn cấu hình trình kích hoạt “API request”, Maildroppa sử dụng cùng account API key được quản lý trên trang này. Phần thiết lập trình kích hoạt có thể tạo key khi chưa có key và sao chép một yêu cầu curl đã chuẩn bị sẵn chứa toàn bộ key.

Điều này có hai hệ quả quan trọng:

• Việc xoay vòng hoặc xóa account key cũng ảnh hưởng đến các hệ thống gửi sự kiện tùy chỉnh đến Automations.
• Ví dụ yêu cầu Automation được sao chép chứa secret trong clipboard, dù key được che trên màn hình.

Trước khi xoay vòng hoặc xóa key, hãy đưa mọi trình kích hoạt yêu cầu API và mọi bên gửi sự kiện bên ngoài vào danh mục kiểm kê tích hợp của bạn.

Đặt lại hoặc thay thế API Key

Sử dụng “Rotate API key” khi bạn cần đặt lại hoặc thay thế thông tin xác thực hiện tại. Maildroppa tạo key mới và vô hiệu hóa key trước đó trong cùng một thao tác.

Sử dụng xoay vòng khi:

• Key có thể đã bị lộ.
• Một người hoặc nhà cung cấp biết key không còn cần quyền truy cập.
• Chính sách bảo mật yêu cầu thay thế thông tin xác thực định kỳ.
• Bạn muốn thay thế key được lưu ở vị trí cũ hoặc không an toàn.

Nhấp vào “Rotate API key” bên dưới key được che. Maildroppa mở hộp thoại cảnh báo giải thích rằng key hiện tại sẽ không thể sử dụng nữa.

Nhấp vào “Rotate API key” trong hộp thoại để tiếp tục hoặc nhấp vào “Cancel” để giữ key hiện tại.

Xoay vòng không có thời gian ân hạn

Sau khi bạn xác nhận xoay vòng, key cũ ngừng hoạt động ngay lập tức. Maildroppa không giữ cho cả key cũ và key mới cùng hợp lệ.

Vì tài khoản chỉ có một key, việc xoay vòng ảnh hưởng đến mọi máy chủ, tác vụ theo lịch, tích hợp, script và bên gửi sự kiện Automation sử dụng key đó.

Hãy dùng trình tự sau cho việc xoay vòng đã lên kế hoạch:

1. Liệt kê mọi tích hợp sử dụng key hiện tại.
2. Chuẩn bị quyền truy cập vào cấu hình secret và quy trình triển khai của từng tích hợp.
3. Chọn một khoảng thời gian bảo trì ngắn nếu việc truy cập API không gián đoạn là quan trọng.
4. Nhấp vào “Rotate API key”, sau đó xác nhận cảnh báo bằng “Rotate API key” trong hộp thoại.
5. Nhấp vào “Copy” để sao chép toàn bộ key mới.
6. Thay thế secret trong mọi tích hợp ngay lập tức.
7. Khởi động lại hoặc triển khai lại các dịch vụ chỉ tải secret khi khởi động.
8. Gửi một yêu cầu được tài liệu hóa, không gây ảnh hưởng, để xác minh từng tích hợp.
9. Kiểm tra các response 401 Unauthorized từ dịch vụ bị bỏ quên vẫn đang sử dụng key cũ.

Nếu cho rằng key hiện tại đã bị xâm phạm, hãy xoay vòng ngay lập tức và chấp nhận khoảng gián đoạn ngắn cần thiết để cập nhật các hệ thống hợp lệ.

Xóa API Key

Xóa key khi tài khoản không còn nên chấp nhận các yêu cầu được xác thực bằng API key.

Nhấp vào “Delete API key” bên dưới key được che. Maildroppa mở hộp thoại cảnh báo giải thích rằng key sẽ bị xóa vĩnh viễn khỏi tài khoản.

Nhấp vào “Delete API key” trong hộp thoại để xóa hoặc nhấp vào “Cancel” để giữ key.

Sau khi xóa:

• Key hiện tại ngừng hoạt động ngay lập tức.
• Trang trở về trạng thái “No API key yet”.
• Các tích hợp máy chủ sử dụng key đã xóa không thể xác thực nữa.
• Các bên gửi yêu cầu API của Automation sử dụng key đó không thể gửi sự kiện nữa.

Xóa key không xóa subscriber, campaign, tag, field, segment, Automation hoặc dữ liệu tài khoản khác. Thao tác này chỉ xóa thông tin xác thực dùng để truy cập các endpoint API được hỗ trợ.

Bạn có thể nhấp vào “Create API key” sau đó để tạo thông tin xác thực mới. Giá trị đã xóa không được khôi phục. Mọi tích hợp phải được cập nhật trước khi có thể sử dụng key mới.

Đặt lại hay xóa: Bạn nên chọn thao tác nào?

Chọn “Rotate API key” khi quyền truy cập API cần tiếp tục với thông tin xác thực mới.

Chọn thao tác xóa khi quyền truy cập API cần dừng hoàn toàn, ít nhất là ở thời điểm hiện tại.

Cả hai thao tác đều vô hiệu hóa key hiện tại ngay lập tức. Xoay vòng tạo key thay thế trong cùng thao tác; xóa key khiến tài khoản không còn key.

Khuyến nghị bảo mật

Giữ các lệnh gọi API trên máy chủ của bạn

Trình duyệt hoặc ứng dụng di động không thể bảo vệ đáng tin cậy một secret được nhúng. Người dùng có thể kiểm tra ứng dụng, request header, source map hoặc lưu lượng mạng và trích xuất key.

Nếu website hoặc ứng dụng cần kích hoạt một thao tác, trước tiên hãy gửi yêu cầu đến backend đã xác thực của riêng bạn. Backend đó sẽ xác thực người dùng và gọi Maildroppa bằng key được lưu trên máy chủ.

Giảm thiểu tối đa việc để lộ key

Chỉ cung cấp key cho các hệ thống cần key. Không phân phối key cho mọi developer hoặc dán key vào nhiều tệp cấu hình cục bộ.

Vì trang hiện quản lý một key trên toàn tài khoản thay vì nhiều key có tên hoặc scope, hãy sử dụng dịch vụ tích hợp nội bộ hoặc proxy nếu nhiều ứng dụng cần được cô lập tốt hơn với nhau.

Che request header

Cấu hình HTTP client, reverse proxy, công cụ observability và trình báo cáo lỗi để che X-API-Key. Một yêu cầu có thể hoạt động chính xác nhưng vẫn làm lộ thông tin xác thực qua debug log.

Giữ các môi trường riêng biệt

Không sử dụng lại key production trong phát triển cục bộ, mã mẫu, ảnh chụp màn hình hoặc test fixture. Lưu secret theo môi trường trong các kho secret tương ứng.

Liên kết “View OpenAPI docs” tự động đưa người dùng production đến tài liệu API production. Luôn xác minh hostname trước khi gửi key thật.

Xoay vòng sau bất kỳ nghi ngờ nào về việc bị lộ

Xóa tin nhắn, commit repository, dòng log hoặc ảnh chụp màn hình không chứng minh rằng chưa ai sao chép key. Nếu toàn bộ giá trị đã bị lộ, hãy xoay vòng key.

Xử lý lỗi API

Sử dụng HTTP status và response body được tài liệu hóa để quyết định tích hợp nên làm gì.

Các trường hợp phổ biến gồm:

• 400 Bad Request — Path, tham số hoặc JSON body không đáp ứng hợp đồng endpoint. So sánh yêu cầu với schema OpenAPI.
• 401 Unauthorized — X-API-Key header bị thiếu, trống, không hợp lệ, đã bị xóa hoặc chứa giá trị cũ sau khi xoay vòng.
• 403 Forbidden — Key đã xác thực không được phép sử dụng thao tác đó.
• 404 Not Found — Path hoặc resource được tham chiếu không tồn tại trong tài khoản này.
• 429 Too Many Requests — Tích hợp đã đạt giới hạn tốc độ API. Tạm dừng yêu cầu và tuân thủ header Retry-After nếu có.
• 5xx — Maildroppa không thể hoàn tất yêu cầu. Thử lại các thao tác an toàn bằng exponential backoff có giới hạn và log không chứa API key.

Không thử lại mọi lỗi một cách mù quáng. Hãy khắc phục response 400, 401, 403 và hầu hết 404 trước khi gửi lại cùng yêu cầu.

Đối với yêu cầu làm thay đổi dữ liệu, hãy xác nhận hành vi retry và idempotency của endpoint trước khi tự động lặp lại yêu cầu. Lỗi kết nối không phải lúc nào cũng chứng minh rằng Maildroppa chưa thực hiện thay đổi.

Khắc phục sự cố

“Create API key” vẫn hiển thị

Hiện tài khoản chưa có key. Nhấp vào nút một lần và chờ yêu cầu hoàn tất.

Nếu tạo key thất bại, hãy tải lại trang trước khi thử lại. Một trang khác hoặc phần thiết lập Automation có thể đã tạo account key.

Key trên trang có vẻ quá ngắn

Trang cố ý chỉ hiển thị năm ký tự đầu tiên và *****. Nhấp vào “Copy” để sao chép toàn bộ giá trị. Không gửi văn bản đã che trong yêu cầu.

“Copy” không đổi thành “Copied!”

Trình duyệt có thể đã chặn quyền truy cập clipboard. Giữ trang trong tab đang hoạt động, cho phép truy cập clipboard nếu được hỏi và nhấp lại vào “Copy”.

Không cố khôi phục key từ văn bản đã che.

Yêu cầu trả về 401 Unauthorized

Kiểm tra rằng:

• Tên header chính xác là X-API-Key.
• Header chứa toàn bộ giá trị, không có các dấu hoa thị hiển thị.
• Tích hợp không gửi Authorization: Bearer thay thế.
• Không có khoảng trắng, dấu ngoặc kép hoặc ký tự xuống dòng được thêm vào secret.
• Không ai đã xoay vòng hoặc xóa account key.
• Dịch vụ đã được khởi động lại nếu chỉ đọc biến môi trường khi khởi động.
• Yêu cầu được gửi đến đúng môi trường Maildroppa API.

Một tích hợp hoạt động nhưng tích hợp khác dừng sau khi xoay vòng

Tích hợp thứ hai có thể vẫn đang sử dụng key cũ. Không có thời gian chồng lấp. Hãy cập nhật secret và khởi động lại mọi tiến trình lưu cấu hình trong bộ nhớ đệm.

Trang OpenAPI hoạt động nhưng endpoint trả về 403

Không phải mọi endpoint ứng dụng đều hỗ trợ xác thực bằng API key. Hãy sử dụng thao tác được tài liệu hóa cho customer API và xác nhận yêu cầu xác thực trên trang OpenAPI.

Yêu cầu trả về 429 Too Many Requests

Giảm các đợt gửi dồn dập, xếp hàng công việc và thử lại sau khoảng thời gian API trả về. Tránh tạo các đợt thử lại song song. Nếu nhiều ứng dụng dùng chung một account key, hãy phối hợp lưu lượng yêu cầu vì chúng chia sẻ giới hạn API của tài khoản.

Danh sách kiểm tra thiết lập đề xuất

Trước khi đưa tích hợp vào sử dụng thường xuyên, hãy xác nhận rằng:

• Key chỉ được lưu trong cấu hình secret phía máy chủ.
• Các yêu cầu sử dụng header X-API-Key.
• Tích hợp sử dụng https://api.maildroppa.com trong production.
• Mọi method, path, tham số và JSON body đều tuân theo tài liệu OpenAPI.
• Log và báo cáo lỗi che key.
• Timeout và số lần retry có giới hạn đã được cấu hình.
• Lỗi 401, 403, 429 và lỗi máy chủ được giám sát.
• Chủ sở hữu tích hợp được ghi nhận.
• Mọi hệ thống dùng chung account key đều được đưa vào kế hoạch xoay vòng.
• Key bị xâm phạm có thể được xoay vòng nhanh chóng.

Trang API Key được thiết kế nhỏ gọn, nhưng các thao tác trên trang ảnh hưởng đến mọi tích hợp API được kết nối với tài khoản. Chỉ tạo key khi cần, giữ key trên các máy chủ đáng tin cậy và lên kế hoạch xoay vòng như một thay đổi thông tin xác thực trên toàn tài khoản.