# URL de suscripción

> Cada lista de contactos tiene una URL de suscripción alojada que añade personas sin clave de API. Conoce el formato de la petición, cómo llamarla de forma segura, sus límites y cómo restablecerla.

Cada lista de contactos tiene una URL de suscripción: un endpoint público que añade una persona a la lista sin clave de API. Úsala para conectar a una lista un formulario de suscripción de tu sitio web o una herramienta sin código capaz de enviar una petición JSON.

```text
POST https://api.emailit.com/subscribe/{token}
```

El `token` es secreto y propio de la lista. Cualquiera que tenga la URL puede añadir direcciones a la lista, así que trátala como una contraseña.

## Encontrar la URL

1. **Abre la lista.** Ve a **Email Marketing → Audiences** y selecciona la lista.

2. **Copia la URL.** Selecciona **Subscribe URL** y copia la URL del cuadro de diálogo.

Con la API, [Obtener una lista de contactos](/es/docs/api-reference/audiences/get/) devuelve el mismo valor en `token`.

## Formato de la petición

Envía una petición `POST` con un cuerpo JSON y `Content-Type: application/json`. No hace falta la cabecera `Authorization`.

- `email` (string, obligatorio): La dirección que se va a suscribir. Se guarda en minúsculas.
- `first_name` (string): El nombre de la persona. Sobrescribe el nombre guardado de un contacto existente.
- `last_name` (string): Los apellidos de la persona. Sobrescriben los apellidos guardados de un contacto existente.
- `custom_fields` (object): Los valores, indexados por la clave del [campo personalizado](/es/docs/contacts/custom-fields/). Sustituye todos los valores de campos personalizados de un contacto existente, así que envíalo solo cuando tengas el conjunto completo.

El endpoint solo lee JSON. Los cuerpos codificados como formulario, que es lo que envía un `<form>` HTML normal, se rechazan con `400` y «Invalid JSON in request body».

### Respuestas

| Estado | Cuerpo | Cuándo |
| --- | --- | --- |
| `200` | `{ "message": "Subscribed successfully" }` | La persona se ha añadido, se ha vuelto a suscribir o ya estaba suscrita. |
| `400` | `{ "error": "Missing required field: email" }` o `{ "error": "Invalid email format" }` | Falta el email o tiene un formato incorrecto, o el cuerpo no es JSON. |
| `404` | `{ "error": "Audience not found" }` | El token es incorrecto o se ha restablecido. |
| `422` | `{ "error": "...", "usage": { ... } }` | La lista ha alcanzado su [límite de suscriptores](/es/docs/audiences/#limits). |
| `429` | | Más de 30 peticiones en un minuto desde la misma dirección IP. |

### Qué hace un alta

- **Dirección nueva:** Emailit crea el contacto y lo suscribe a la lista.
- **Contacto existente que no está en la lista:** Emailit actualiza los nombres y los campos personalizados que has enviado y suscribe el contacto.
- **Suscriptor existente que se había dado de baja:** Emailit lo vuelve a suscribir.
- **Suscriptor existente que está suscrito:** no cambia nada salvo la fecha de suscripción, y la respuesta sigue siendo `200`.

Las altas mediante la URL de suscripción no envían [eventos de webhook](/es/docs/webhooks/event-types/) `subscriber.*` ni `contact.*` y no inician las automatizaciones **Added to audience**. Tampoco cambian el estado de marketing de un contacto: si el contacto se había dado de baja de forma global, las campañas lo siguen omitiendo hasta que lo vuelvas a suscribir en la página Contacts.

## Conectar un formulario de suscripción

La URL de suscripción no tiene protección contra bots y solo acepta JSON. La configuración más segura es enviar el formulario a tu propio servidor, comprobarlo allí y llamar a la URL de suscripción desde el servidor. Así el token no aparece en el código fuente de tu página y puedes bloquear el spam antes de que llegue a tu lista.

1. **Añade el formulario a tu página.** Envíalo a un endpoint de tu propio sitio. El campo oculto `website` es un honeypot: las personas no lo ven, pero los bots suelen rellenarlo.

```html title="signup.html"
<form id="signup" method="post" action="/newsletter">
  <label for="email">Email</label>
  <input id="email" name="email" type="email" required>

  <label for="first_name">First name</label>
  <input id="first_name" name="first_name" type="text">

  <!-- Honeypot: hidden from people, often filled in by bots -->
  <div style="position:absolute;left:-10000px" aria-hidden="true">
    <input name="website" type="text" tabindex="-1" autocomplete="off">
  </div>

  <button type="submit">Subscribe</button>
  <p class="status" role="status"></p>
</form>
```

2. **Procesa el formulario en tu servidor.** Descarta los envíos que rellenan el honeypot, comprueba un CAPTCHA si usas uno y reenvía los campos a la URL de suscripción como JSON. Guarda el token en una variable de entorno como `EMAILIT_SUBSCRIBE_TOKEN`. Consulta los [ejemplos de servidor](#server-examples) más abajo.

3. **Pruébalo.** Envía el formulario con tu propia dirección y comprueba que apareces en la tabla de suscriptores de la lista.

### Ejemplos de servidor

**Node.js**

```javascript title="server.js"
import express from 'express';

const app = express();

app.post('/newsletter', express.urlencoded({ extended: false }), async (req, res) => {
  // Bots fill in the honeypot. Pretend it worked and stop.
  if (req.body.website) return res.redirect(303, '/thanks');

  const response = await fetch(
    `https://api.emailit.com/subscribe/${process.env.EMAILIT_SUBSCRIBE_TOKEN}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: req.body.email,
        first_name: req.body.first_name || undefined,
      }),
    },
  );

  if (!response.ok) {
    const { error } = await response.json().catch(() => ({}));
    return res.status(response.status).send(error || 'Could not subscribe.');
  }

  res.redirect(303, '/thanks');
});

app.listen(3000);
```

**PHP**

```php title="newsletter.php"
<?php
// Bots fill in the honeypot. Pretend it worked and stop.
if (!empty($_POST['website'])) {
    header('Location: /thanks', true, 303);
    exit;
}

$token = getenv('EMAILIT_SUBSCRIBE_TOKEN');
$ch = curl_init("https://api.emailit.com/subscribe/{$token}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => $_POST['email'] ?? '',
        'first_name' => $_POST['first_name'] ?? null,
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    http_response_code($status);
    echo json_decode($body, true)['error'] ?? 'Could not subscribe.';
    exit;
}

header('Location: /thanks', true, 303);
```

**cURL**

```bash
curl "https://api.emailit.com/subscribe/$EMAILIT_SUBSCRIBE_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "first_name": "Ada" }'
```

Si tu página envía el formulario con JavaScript en lugar de recargar la página entera, llama a tu propio endpoint con `fetch` y deja la llamada a Emailit en el servidor:

```javascript title="signup.js"
document.querySelector('#signup').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.target);
  const response = await fetch('/newsletter', { method: 'POST', body: new URLSearchParams(form) });
  event.target.querySelector('.status').textContent = response.ok
    ? 'Thanks, you are subscribed.'
    : 'Something went wrong. Please try again.';
});
```

### Límite de velocidad y volúmenes mayores

La URL de suscripción acepta 30 peticiones por minuto desde cada dirección IP y devuelve `429` por encima de esa cifra. Cuando tu servidor reenvía todas las altas, todas proceden de la IP de tu servidor, así que las 30 por minuto se aplican a todo tu sitio. Si esperas más, llama en su lugar a [Añadir un suscriptor](/es/docs/api-reference/audiences/subscribers/add/) desde tu servidor con una clave de API. Ese endpoint también devuelve `409` para las personas que ya están suscritas e inicia las automatizaciones **Added to audience**, por ejemplo para enviar un email de bienvenida.

## Confirmar las altas

La URL de suscripción añade a las personas de inmediato. Emailit no envía un email de confirmación ni pide a la persona que confirme su dirección (doble opt-in).

Si quieres altas confirmadas, incorpora la confirmación a tu propio flujo: cuando alguien envíe el formulario, guarda la petición en tu servidor y [envíale un email](/es/docs/email-api/send-email/) con un enlace de confirmación que apunte a tu sitio. Llama a la URL de suscripción solo después de que abra ese enlace.

## Restablecer la URL

Restablece el token si la URL se ha filtrado o estás recibiendo altas de spam. La URL antigua deja de funcionar de inmediato y devuelve `404`.

1. **Abre el cuadro de diálogo.** En la página de la lista, selecciona **Subscribe URL**.

2. **Restablece.** Selecciona **Reset token** y confirma. Emailit genera una URL nueva.

3. **Actualiza tus integraciones.** Sustituye el token en todos los sitios donde lo uses, como la variable `EMAILIT_SUBSCRIBE_TOKEN` de tu servidor.

El token solo se puede restablecer en el panel.

## Ver también

  - [Gestionar los suscriptores](/es/docs/audiences/subscribers/): Añade personas con la API y gestiona las nuevas suscripciones.
  - [Bajas](/es/docs/audiences/unsubscribes/): Permite que las personas salgan de tus listas.

---
Fuente: https://emailit.com/es/docs/audiences/subscribe-url/