> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.laposta.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.laposta.org/_mcp/server.

# Sincronizar suscriptores a través de la API

> Mantén tu lista igual que tu tienda online o CRM: añadir, actualizar, darse de baja y gestionar errores.

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`**

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

**`PHP`**

```php title="PHP"
$laposta = new Laposta('TU_CLAVE_API');
$velden = $laposta->fieldApi()->all('BaImMu3JZA');
```

> **Tip**
>
> 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`**

```bash title="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`**

```php title="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`**

```bash title="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`**

```php title="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](/relaties/relatie-verwijderen) | 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)](/lijsten/lijst-synchroniseren-bulk): esto te permite enviar hasta 500.000 suscriptores como JSON en una sola llamada.

**`JSON`**

```json title="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`**

```php title="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.

> **Warning**
>
> 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](mailto: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](/veelgemaakte-fouten-met-de-api).
* 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](/veelgemaakte-fouten-met-de-api).
* 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.

## Artículos relacionados

#### [Usar webhooks para modificaciones en una lista](/webhooks-gebruiken)

Con un webhook, Laposta avisa a tu sistema en cuanto alguien se suscribe, se da de baja…

#### [¿Cuáles son los errores más comunes con la API?](/veelgemaakte-fouten-met-de-api)

Errores habituales al conectar con la API de Laposta, con el mensaje de error que…

#### [¿Cuáles son los límites y mensajes de error de la API?](/api-limieten-en-foutmeldingen)

Cuántas solicitudes por minuto permite la API y qué códigos de estado y de error puedes…