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 cũng truy cập Adapty Mail qua entry point khác, hãy gửi customer_user_id — cùng user ID mà nguồn đó gửi. Đối với Adapty SDK, đó là giá trị bạn truyền vào Adapty.identify(); FunnelFox gửi ID mà nó đang lưu. Giá trị này không quyết định hồ sơ người dùng nào được chọn — địa chỉ email mới là thứ làm điều đó. Điều nó bổ sung là một cách thứ hai để tìm hồ sơ: một sự kiện giao dịch mang theo nó có thể được xử lý mà không cần email, và một yêu cầu xóa có thể dùng nó thay vì địa chỉ email.

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"
    }
  }'

device_info mô tả thiết bị của người dùng. Đối tượng này là tùy chọn, nhưng platform phải có mặt bất cứ khi nào bạn gửi nó.

Trường	Tùy chọn	Bộ lọc phân khúc	Ghi chú
platform	Không	Có
device	Có	Có	Mẫu thiết bị.
os	Có	Có
locale	Có	Có	Adapty Mail dùng trường này để quyết định gửi bản dịch nào của chiến dịch đã bản địa hóa. Người dùng không có locale sẽ nhận email bằng tiếng Anh.
app_version	Có	Có	So sánh theo thứ tự phiên bản, vì vậy 1.10.0 xếp cao hơn 1.9.0.
timezone	Có	Không	Xác định thời điểm người dùng nhận email. Nếu không có, Adapty Mail coi họ là UTC, nên khung giờ gửi 08:00–21:00 sẽ theo UTC thay vì múi giờ thực của họ.

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ố đó. Adapty Mail sẽ xóa dữ liệu đã lưu, nhưng không chặn địa chỉ đó: nếu nguồn gửi lại, một hồ sơ người dùng mới sẽ xuất hiện mà không có lịch sử. Để loại bỏ ai đó vĩnh viễn, hãy ngăn nguồn không gửi dữ liệu của họ nữa.

Một yêu cầu xóa bị timeout khiến bạn không chắc liệu nó có được xử lý không, nên bạn gửi lại lần nữa. Lần gọi thứ hai này an toàn khi bạn xác định hồ sơ người dùng bằng external_profile_id hoặc customer_user_id — nó thành công và không thay đổi gì. Một lần gọi thứ hai chỉ mang theo email sẽ trả về 404, vì lần xóa đầu tiên đã xóa địa chỉ mà nó sẽ khớp. Tài liệu tham khảo Delete profile liệt kê các mã phản hồi.

Á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