Sincronizar suscriptores a través de la API

Con una conexión API, las suscripciones de tu tienda online, CRM o sitio web llegan automáticamente a la lista adecuada.

Obtener y guardar los campos

Los campos personalizados se envían bajo custom_fields, utilizando el custom_name del campo como clave. Este nombre a veces difiere de lo que esperas: el campo que en la aplicación se llama «Nombre» (en neerlandés Voornaam), en la API suele llamarse voornaam. Por lo tanto, obtén estos nombres una sola vez y guárdalos en tu propio código.

curl "https://api.laposta.nl/v2/field?list_id=BaImMu3JZA" \
  -u TU_CLAVE_API:

No consultes los nombres de los campos en cada suscripción; guárdalos en tu propio sistema y actualízalos, por ejemplo, una vez al día. Los campos rara vez cambian y cada llamada cuenta para tu límite de 30 solicitudes por minuto (120 en una cuenta de pago). De lo contrario, en una tienda online con mucho tráfico agotarás el límite rápidamente solicitando datos que ya tenías.

Añadir y actualizar un suscriptor

Envía la dirección de correo electrónico, la dirección IP y tus campos personalizados

La dirección IP es obligatoria: con ella registras de dónde procede la suscripción. La necesitas para poder demostrar que alguien se ha suscrito por sí mismo.

curl

curl https://api.laposta.nl/v2/member \
  -u TU_CLAVE_API: \
  -d list_id=BaImMu3JZA \
  -d ip=198.51.100.10 \
  -d email=nuevo.suscriptor@example.net \
  -d source_url=https://example.net/suscribirse \
  -d custom_fields[voornaam]=Sanne

PHP

$laposta = new Laposta('TU_CLAVE_API');
$relatie = $laposta->memberApi()->create('BaImMu3JZA', [
    'ip' => '198.51.100.10',
    'email' => 'nuevo.suscriptor@example.net',
    'source_url' => 'https://example.net/suscribirse',
    'custom_fields' => ['voornaam' => 'Sanne'],
]);

Gestiona el mensaje si la dirección ya existe

Si la dirección ya está en la lista, recibirás un 400 con el código de error 204. Si en ese caso prefieres actualizar los datos existentes en lugar de recibir un mensaje de error, establece options[upsert] en true.

Actualiza los datos más adelante

Haz un POST directamente sobre el suscriptor para actualizar sus datos. Solo tienes que enviar lo que cambia. Los demás campos permanecerán sin cambios. Para ello puedes utilizar el member_id o simplemente la dirección de correo electrónico.

curl

curl https://api.laposta.nl/v2/member/nuevo.suscriptor@example.net \
  -u TU_CLAVE_API: \
  -d list_id=BaImMu3JZA \
  -d custom_fields[woonplaats]=Madrid

PHP

$laposta->memberApi()->update('BaImMu3JZA', 'nuevo.suscriptor@example.net', [
    'custom_fields' => ['woonplaats' => 'Madrid'],
]);

Dar de baja o eliminar un suscriptor

Si alguien se da de baja a través de tu propio sitio web, lo mejor es cambiar el estado del suscriptor a dado de baja. Utiliza la opción de eliminar únicamente cuando alguien solicite borrar por completo sus datos.

Qué haces	Cómo	Qué ocurre
Darse de baja	modificar con `state` en `unsubscribed`	El suscriptor sigue existiendo y no recibe nada más. Si más adelante vuelve a suscribirse, lo verás reflejado en el historial.
Eliminar	Eliminar suscriptor	El suscriptor desaparece definitivamente, incluido su historial.

Sincronizar toda una lista de una sola vez

Si sincronizas suscriptor por suscriptor, cuando tengas miles de suscriptores tardarás mucho tiempo y alcanzarás el límite. Utiliza para ello Sincronizar lista (bulk): esto te permite enviar hasta 500.000 suscriptores como JSON en una sola llamada.

JSON

{
  "actions": ["add", "update"],
  "members": [
    { "email": "primero@example.net", "custom_fields": { "voornaam": "Sanne" } },
    { "email": "segundo@example.net" }
  ]
}

Con la biblioteca PHP envías el mismo contenido como un array:

PHP

$laposta->listApi()->syncMembers('BaImMu3JZA', [
    'actions' => ['add', 'update'],
    'members' => [
        ['email' => 'primero@example.net', 'custom_fields' => ['voornaam' => 'Sanne']],
        ['email' => 'segundo@example.net'],
    ],
]);

Con la acción unsubscribe_excluded das de baja a todos los que no estén incluidos en tu envío. Utiliza esto únicamente si tu sistema es la fuente de referencia, y no si solo estás enviando una parte de tu archivo.

La función bulk no está activada por defecto. Solo está disponible para cuentas de pago y Laposta debe activarla para cada cuenta. Si recibes un 401 con “Not permitted to issue bulk requests (1)”, ponte en contacto con el servicio de asistencia en helpdesk@laposta.nl indicando tu número de cuenta.

¿Qué debes tener en cuenta?

No puedes vaciar un campo de opción múltiple enviando una lista vacía. Si envías una lista vacía para un campo select_multiple, las opciones existentes no se borrarán. Ver: Errores más comunes.
Si envías una etiqueta como texto simple, se borrarán todas las etiquetas existentes. Envía "labels": ["Cliente"] y no "labels": "Cliente". Si lo haces mal, recibirás igualmente un 200 con edited_count sin ningún mensaje de error, pero todas las etiquetas quedarán vacías. Ver: Errores más comunes.
Un ID desconocido no devuelve un 404, sino un 400 con el código 203. Asegúrate de tenerlo en cuenta en tus pruebas.
El límite es más ajustado de lo que parece en una cuenta gratuita: 30 solicitudes por minuto. Incorpora un tiempo de espera basado en el encabezado Retry-After en lugar de volver a intentarlo inmediatamente.