L’API Adapty Mail vous permet d’envoyer des profils utilisateurs et des transactions à Adapty Mail directement depuis votre serveur, sans passer par le SDK Adapty. Utilisez-la lorsque vous souhaitez :

• Ajoutez des abonnés quand vous n’avez pas encore de base dans Adapty Mail.
• Réutilisez la base d’abonnés de vos autres apps.
• Alimentez Adapty Mail en serveur à serveur, avec votre backend comme source de vérité.

Avant de commencer

Vous avez également besoin de votre clé API et de votre URL de base :

• Clé API secrète : Dans Adapty Mail, rendez-vous dans Settings > Project et copiez la Secret key. La clé est propre à chaque projet, ce qui permet à l’API de savoir à quel projet les données appartiennent.
• URL de base : Toutes les requêtes sont envoyées à https://api-mail.adapty.io.
• Authentification : Transmettez la clé dans l’en-tête Authorization sous la forme Bearer {your_secret_api_key}.

Envoyer des profils utilisateurs

Un profil contient l’adresse e-mail et les attributs de l’utilisateur. Pour en créer ou en mettre à jour un, envoyez une requête POST à /api/v1/profile/save/.

Trois champs sont obligatoires :

• Un external_profile_id stable, géré par votre application ou votre backend
• L’email auquel Adapty Mail envoie les campagnes
• external_created_at — la date de création de l’utilisateur, utilisable dans les segments

Si la même personne accède également à Adapty Mail via un autre point d’entrée, envoyez customer_user_id — le même identifiant utilisateur que la source transmet. Pour le SDK Adapty, c’est la valeur que vous passez à Adapty.identify() ; FunnelFox envoie celui qu’il détient. Ce paramètre ne détermine pas sur quel profil l’utilisateur atterrit ; c’est l’adresse e-mail qui s’en charge. Il ajoute simplement une deuxième façon de retrouver le profil : un événement de transaction qui le contient peut être résolu sans adresse e-mail, et une suppression peut le désigner à la place de l’adresse.

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 décrit l’appareil de l’utilisateur. L’objet est facultatif, mais platform doit être présent dès lors que vous l’envoyez.

Champ	Facultatif	Filtre de segment	Notes
platform	Non	Oui
device	Oui	Oui	Le modèle d’appareil.
os	Oui	Oui
locale	Oui	Oui
app_version	Oui	Oui	Comparé dans l’ordre des versions, donc 1.10.0 est supérieur à 1.9.0.
timezone	Oui	Non	Définit quand l’utilisateur reçoit les e-mails. Sans ce champ, Adapty Mail le traite en UTC, donc la fenêtre d’envoi 08h00–21h00 suit l’UTC plutôt que son propre fuseau horaire.

Consultez la référence Save profile pour tous les champs disponibles.

Envoyer des événements de transaction

Tous les flows sauf never purchased sont pilotés par l’historique des achats. Envoyez les événements de transaction d’un profil au fur et à mesure que vous gérez les achats, les renouvellements et les annulations, afin qu’Adapty Mail puisse le placer dans le bon flow. Les événements de transaction alimentent également l’attribution des revenus. Ne les ignorez que si vous menez exclusivement des campagnes never purchased.

Pour enregistrer une transaction, envoyez une requête POST à /api/v1/profile/transaction-event/save/. Utilisez le même external_profile_id que celui envoyé avec le profil afin qu’Adapty Mail associe la transaction au bon utilisateur.

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

Consultez la référence Save transaction event pour tous les champs disponibles.

Vous pouvez envoyer une transaction avant que le profil existe. Adapty Mail conserve l’événement non attaché, puis le lie au profil lors du prochain enregistrement incluant le même external_profile_id.

Supprimer un profil

Pour répondre à une demande de droit à l’effacement, envoyez les identifiants du profil à /api/v1/profile/delete/. Adapty Mail efface les données personnelles du profil et annule ses e-mails planifiés.

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

Identifiez le profil par external_profile_id, customer_user_id ou email — envoyez au moins un de ces champs. Adapty Mail efface les données stockées, mais ne bloque pas l’adresse : si une source la renvoie, un nouveau profil apparaît sans historique. Pour exclure définitivement quelqu’un, empêchez la source d’envoyer ses données.

Une requête de suppression qui expire vous laisse dans l’incertitude quant à son résultat, alors vous la renvoyez. Ce deuxième appel est sans risque si vous identifiez le profil par external_profile_id ou customer_user_id — il réussit sans rien modifier. Un deuxième appel portant uniquement email renvoie 404, car la première suppression a effacé l’adresse qu’il aurait trouvée. La référence Supprimer un profil liste les codes de réponse.

Associez vos événements aux flows

Envoyez le event_type qui correspond à ce qui s’est passé. Adapty Mail déduit l’état du profil à partir de son historique d’événements et le dirige vers le flow correspondant.

event_type	L’envoyer quand	Flow
subscription_started	Un utilisateur démarre un nouvel abonnement.	Actif — pas de flow de réengagement
subscription_renewed	Un abonnement se renouvelle automatiquement.	Actif — pas de flow de réengagement
subscription_renewal_reactivated	Un utilisateur réactive le renouvellement automatique.	Actif — pas de flow de réengagement
non_subscription_purchase	Un utilisateur effectue un achat unique.	Actif — pas de flow de réengagement
subscription_renewal_cancelled	Un utilisateur désactive le renouvellement automatique (l’abonnement reste actif jusqu’à expiration).	Renouvellement annulé
billing_issue_detected	Un paiement de renouvellement échoue.	Problème de facturation
entered_grace_period	Le paiement échoue mais l’utilisateur est encore dans le délai de grâce.	Problème de facturation
subscription_expired	Un abonnement expire et l’accès prend fin.	Expiré
subscription_refunded	Un achat d’abonnement est remboursé.	Remboursé
non_subscription_purchase_refunded	Un achat unique est remboursé.	Remboursé