Adapty Mail API cho phép bạn gửi hồ sơ người dùng và giao dịch đến Adapty Mail trực tiếp từ máy chủ, không cần chuyển dữ liệu qua Adapty SDK. Sử dụng API này khi bạn muốn:

• Thêm người đăng ký khi bạn chưa có danh sách trong Adapty Mail.
• Tái sử dụng danh sách người đăng ký từ các ứng dụng khác của bạn.
• Cung cấp dữ liệu cho Adapty Mail theo phương thức server-to-server, với backend của bạn là nguồn dữ liệu chính.

Trước khi bắt đầu

Bạn cũng cần API key và base URL:

• Secret API key: Trong Adapty Mail, vào Settings > Project và sao chép Secret key. Key này gắn với từng project, giúp API xác định dữ liệu thuộc về project nào.
• Base URL: Tất cả các request đều gửi đến https://api-mail.adapty.io.
• Authentication: Gửi key trong header Authorization theo dạng Bearer {your_secret_api_key}.

Gửi hồ sơ người dùng

Một hồ sơ chứa email và các thuộc tính của người dùng. Để tạo hoặc cập nhật hồ sơ, gửi request POST đến /api/v1/profile/save/.

Ba trường bắt buộc:

• external_profile_id ổn định do ứng dụng hoặc backend của bạn quản lý
• email mà Adapty Mail dùng để gửi chiến dịch
• external_created_at — thời điểm tạo người dùng, có thể dùng trong phân khúc

Nếu cùng một người dùng cũng tiếp cận Adapty Mail thông qua Adapty SDK, hãy thêm customer_user_id — đây là ID người dùng của bạn, tức là ID bạn truyền vào Adapty.identify(). Adapty Mail sẽ khớp theo ID này và giữ cả hai nguồn trong cùng một hồ sơ người dùng, thay vì tạo ra một bản sao trùng lặp khiến người dùng nhận được email hai lần.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/save/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_profile_id": "user_12345",
    "external_created_at": "2026-06-01T10:30:00Z",
    "email": "jane@example.com",
    "country": "US",
    "custom_attributes": {
      "plan": "trial"
    }
  }'

Xem tài liệu tham khảo Save profile để biết tất cả các trường có sẵn.

Gửi sự kiện giao dịch

Mọi flow ngoại trừ flow chưa từng mua hàng đều dựa vào lịch sử mua hàng. Gửi sự kiện giao dịch của hồ sơ khi xử lý các giao dịch mua, gia hạn và hủy, để Adapty Mail có thể đưa hồ sơ vào đúng flow. Sự kiện giao dịch cũng hỗ trợ attribution doanh thu. Bỏ qua bước này chỉ khi bạn chỉ chạy chiến dịch chưa từng mua hàng mà thôi.

Để ghi lại một giao dịch, gửi request POST đến /api/v1/profile/transaction-event/save/. Dùng cùng external_profile_id đã gửi với hồ sơ để Adapty Mail liên kết giao dịch với đúng người dùng.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/transaction-event/save/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_type": "subscription_started",
    "event_id": "evt_abc123",
    "event_datetime": "2026-06-10T14:20:05Z",
    "external_profile_id": "user_12345",
    "store": "app_store",
    "store_product_id": "premium_monthly",
    "store_transaction_id": "1000000123456789",
    "store_original_transaction_id": "1000000123456789",
    "purchased_at": "2026-06-10T14:20:00Z",
    "originally_purchased_at": "2026-06-10T14:20:00Z",
    "price_usd": "9.99"
  }'

Xem tài liệu tham khảo sự kiện lưu transaction để biết tất cả các trường có sẵn.

Bạn có thể gửi một transaction trước khi hồ sơ người dùng tồn tại. Adapty Mail sẽ giữ sự kiện ở trạng thái chưa liên kết, sau đó liên kết nó với hồ sơ người dùng trong lần lưu tiếp theo có cùng external_profile_id.

Xóa hồ sơ người dùng

Để thực hiện yêu cầu xóa dữ liệu, hãy gửi các định danh của hồ sơ người dùng đến /api/v1/profile/delete/. Adapty Mail sẽ xóa dữ liệu cá nhân của hồ sơ và hủy các email đã lên lịch.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/delete/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_profile_id": "user_12345"
  }'

Xác định hồ sơ người dùng bằng external_profile_id, customer_user_id, hoặc email — cần gửi ít nhất một trong số này. Việc xóa là vĩnh viễn: một yêu cầu lưu sau đó mang cùng các định danh sẽ không tạo lại hồ sơ người dùng.

Để thực hiện thử lại an toàn, hãy xác định hồ sơ người dùng bằng external_profile_id hoặc customer_user_id. Lặp lại thao tác xóa chỉ dùng email sẽ trả về 404, vì việc xóa đã xóa sạch địa chỉ đã lưu. Xem tài liệu tham khảo Xóa hồ sơ người dùng để biết thêm chi tiết.

Ánh xạ sự kiện vào flow

Gửi event_type tương ứng với những gì đã xảy ra. Adapty Mail suy ra trạng thái của hồ sơ từ lịch sử sự kiện và chuyển hồ sơ vào flow phù hợp.

event_type	Gửi khi	Flow
subscription_started	Người dùng bắt đầu gói đăng ký mới.	Đang hoạt động — không có flow tái tương tác
subscription_renewed	Gói đăng ký tự động gia hạn.	Đang hoạt động — không có flow tái tương tác
subscription_renewal_reactivated	Người dùng bật lại tự động gia hạn.	Đang hoạt động — không có flow tái tương tác
non_subscription_purchase	Người dùng thực hiện sản phẩm mua một lần.	Đang hoạt động — không có flow tái tương tác
subscription_renewal_cancelled	Người dùng tắt tự động gia hạn (vẫn còn hiệu lực đến khi hết hạn).	Đã hủy gia hạn
billing_issue_detected	Thanh toán gia hạn thất bại.	Vấn đề thanh toán
entered_grace_period	Thanh toán thất bại nhưng người dùng vẫn đang trong thời gian ân hạn.	Vấn đề thanh toán
subscription_expired	Gói đăng ký hết hạn và quyền truy cập bị ngừng.	Đã hết hạn
subscription_refunded	Giao dịch mua gói đăng ký được hoàn tiền.	Đã hoàn tiền
non_subscription_purchase_refunded	Sản phẩm mua một lần được hoàn tiền.	Đã hoàn tiền