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 chưa có danh sách nào 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 kiểu 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 và sao chép secret API key của bạn. Key này gắn với từng project, giúp API biết 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.
• Xác thực: 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

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": "[email protected]",
    "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ó thể dùng.

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 Save transaction event để biết tất cả các trường có thể dùng.

Á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