La API de Adapty Mail te permite enviar perfiles de usuario y transacciones a Adapty Mail directamente desde tu servidor, sin enrutar los datos a través del SDK de Adapty. Úsala cuando quieras:

• Agrega suscriptores cuando aún no tienes una base en Adapty Mail.
• Reutiliza la base de suscriptores de tus otras apps.
• Alimenta Adapty Mail de servidor a servidor, con tu backend como fuente de verdad.

Antes de empezar

También necesitas tu clave API y la URL base:

• Clave de API secreta: En Adapty Mail, ve a Settings > Project y copia la Secret key. La clave es específica del proyecto, de modo que la API sabe a qué proyecto pertenecen los datos.
• URL base: Todas las solicitudes van a https://api-mail.adapty.io.
• Autenticación: Envía la clave en el encabezado Authorization como Bearer {your_secret_api_key}.

Enviar perfiles de usuario

Un perfil contiene el email y los atributos del usuario. Para crear o actualizar uno, envía una solicitud POST a /api/v1/profile/save/.

Se requieren tres campos:

• Un external_profile_id estable que tu app o backend gestione
• El email al que Adapty Mail envía las campañas
• external_created_at — la fecha de creación del usuario, que puedes usar en segmentos

Si la misma persona también llega a Adapty Mail a través de otro punto de entrada, envía customer_user_id — el mismo ID de usuario que utiliza la fuente. En el SDK de Adapty es el valor que pasas a Adapty.identify(); FunnelFox envía el que tiene almacenado. Esto no determina en qué perfil aterriza el usuario; eso lo decide la dirección de email. Lo que aporta es una segunda forma de encontrar el perfil: un evento de transacción que lo incluya se resuelve sin necesidad de email, y una eliminación puede identificarlo por este valor en lugar de por la direcció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"
    }
  }'

device_info describe el dispositivo del usuario. El objeto es opcional, pero platform debe estar presente siempre que lo envíes.

Campo	Opcional	Filtro de segmento	Notas
platform	No	Sí
device	Sí	Sí	El modelo del dispositivo.
os	Sí	Sí
locale	Sí	Sí
app_version	Sí	Sí	Se compara por orden de versión, por lo que 1.10.0 está por encima de 1.9.0.
timezone	Sí	No	Define cuándo recibe el usuario los correos. Sin este campo, Adapty Mail lo trata como UTC, por lo que la ventana de envío de 08:00–21:00 sigue UTC en lugar de la hora local del usuario.

Consulta la referencia de Save profile para ver todos los campos disponibles.

Enviar eventos de transacción

Todos los flows excepto el de nunca han comprado se basan en el historial de compras. Envía los eventos de transacción de un perfil a medida que gestiones compras, renovaciones y cancelaciones, para que Adapty Mail pueda ubicarlo en el flow correcto. Los eventos de transacción también alimentan la atribución de ingresos. Omítelos solo si ejecutas campañas exclusivamente de nunca han comprado.

Para registrar una transacción, envía una petición POST a /api/v1/profile/transaction-event/save/. Usa el mismo external_profile_id que enviaste con el perfil para que Adapty Mail vincule la transacción al usuario correcto.

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

See the Save transaction event reference for every available field.

You can send a transaction before the profile exists. Adapty Mail keeps the event unattached, then links it to the profile on the next save that includes the same external_profile_id.

Eliminar un perfil

Para atender una solicitud de derecho al olvido, envía los identificadores del perfil a /api/v1/profile/delete/. Adapty Mail borra los datos personales del perfil y cancela sus correos programados.

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

Identifica el perfil mediante external_profile_id, customer_user_id o email — envía al menos uno. Adapty Mail borra los datos almacenados, pero no bloquea la dirección: si una fuente la vuelve a enviar, aparece un nuevo perfil sin historial. Para excluir a alguien de forma permanente, impide que la fuente envíe sus datos.

Una solicitud de eliminación que agota el tiempo de espera te deja sin saber si llegó a procesarse, así que la reenvías. Esa segunda llamada es segura cuando identificas el perfil por external_profile_id o customer_user_id — tiene éxito y no cambia nada. Una segunda llamada que lleva solo email devuelve 404, porque la primera eliminación borró la dirección con la que habría coincidido. La referencia de Eliminar perfil lista los códigos de respuesta.

Asigna tus eventos a los flows

Envía el event_type que corresponda a lo que ocurrió. Adapty Mail deduce el estado del perfil a partir del historial de eventos y lo enruta al flow correspondiente.

event_type	Envíalo cuando	Flow
subscription_started	Un usuario inicia una nueva suscripción.	Activo — sin flow de reenganche
subscription_renewed	Una suscripción se renueva automáticamente.	Activo — sin flow de reenganche
subscription_renewal_reactivated	Un usuario reactiva la renovación automática.	Activo — sin flow de reenganche
non_subscription_purchase	Un usuario realiza una compra única.	Activo — sin flow de reenganche
subscription_renewal_cancelled	Un usuario desactiva la renovación automática (sigue activa hasta que expire).	Renovación cancelada
billing_issue_detected	Falla el pago de una renovación.	Problema de facturación
entered_grace_period	El pago falla pero el usuario sigue en el período de gracia.	Problema de facturación
subscription_expired	Una suscripción caduca y se pierde el acceso.	Expirada
subscription_refunded	Se reembolsa una compra de suscripción.	Reembolsada
non_subscription_purchase_refunded	Se reembolsa una compra única.	Reembolsada