Leads

Crea, lista, actualiza y elimina leads, y gestiona sus segmentos, tags y atributos vía API.

Gestiona los leads (contactos) de tu proyecto de ReallyQuickEmails vía API: CRUD, segmentos, tags y atributos.

Autenticacion

Todas las peticiones requieren un Bearer token:

text

Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ver más en API Pública v1.

Endpoints

POST /v1/leads

Crea o actualiza uno o muchos leads. Si el email ya existe en el proyecto, se actualiza (upsert).

Campo	Tipo	Requerido	Descripción
email	string	Sí (si no hay `leads`)	Email del lead
data	object	No	Atributos custom (nombre, teléfono, etc.)
segment_ids	string[]	No	UUIDs de segmentos a asignar
leads	array	Sí (si no hay `email`)	Array de leads para bulk (máximo 1,000)

Si el mismo email se repite dentro de una petición bulk, se deduplica y gana la última ocurrencia.

bash

# Individual
curl -X POST https://api.reallyquickemails.com/v1/leads \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "data": { "name": "Jane", "phone": "+1234567890" },
    "segment_ids": ["uuid-segmento-1"]
  }'

# Bulk (hasta 1,000)
curl -X POST https://api.reallyquickemails.com/v1/leads \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "email": "jane@acme.com", "data": { "name": "Jane" } },
      { "email": "mike@store.co", "data": { "name": "Mike" }, "segment_ids": ["uuid"] }
    ]
  }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

// Individual
await rqe.leads.upsert({
  email: 'jane@acme.com',
  data: { name: 'Jane', phone: '+1234567890' },
  segment_ids: ['uuid-segmento-1'],
});

// Bulk (hasta 1,000)
await rqe.leads.upsertMany({
  leads: [
    { email: 'jane@acme.com', data: { name: 'Jane' } },
    { email: 'mike@store.co', data: { name: 'Mike' }, segment_ids: ['uuid'] },
  ],
});

Response (201):

json

{
  "success": true,
  "total": 2,
  "leads": [
    { "id": "uuid", "email": "jane@acme.com", "created": true },
    { "id": "uuid", "email": "mike@store.co", "created": false }
  ]
}

created: true = lead nuevo. created: false = lead existente actualizado.

Si algún segment_id no existe en el proyecto, los leads se crean igual y la respuesta incluye un campo adicional warnings (array de strings) con los segmentos no encontrados.

GET /v1/leads

Lista leads con paginación, ordenados por fecha de creación descendente.

Parámetro	Tipo	Default	Descripción
page	number	1	Página
per_page	number	50	Resultados por página (máx. 200)
search	string	—	Buscar por email o nombre
segment_id	UUID	—	Filtrar por segmento

bash

curl "https://api.reallyquickemails.com/v1/leads?page=1&per_page=50" \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx"

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.list({ page: 1, per_page: 50 });

Response (200):

json

{
  "success": true,
  "data": [
    { "id": "uuid", "email": "jane@acme.com", "data": { "name": "Jane" }, "created_at": "...", "updated_at": "..." }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}

GET /v1/leads/:id

Obtén un lead por ID (UUID), incluyendo sus segmentos.

bash

curl https://api.reallyquickemails.com/v1/leads/uuid-del-lead \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx"

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.get('uuid-del-lead');

Response (200):

json

{
  "success": true,
  "lead": {
    "id": "uuid",
    "email": "jane@acme.com",
    "data": { "name": "Jane" },
    "created_at": "...",
    "updated_at": "...",
    "shopify_customer_id": null,
    "segment_ids": ["uuid-1", "uuid-2"]
  }
}

shopify_customer_id es el ID del cliente en Shopify cuando el lead proviene de la sincronización con Shopify; null en caso contrario.

PUT /v1/leads/:id

Actualiza un lead. Al menos uno de email, data, o segment_ids es requerido.

Campo	Tipo	Requerido	Descripción
email	string	No*	Nuevo email del lead
data	object	No*	Reemplaza el objeto completo de atributos (no hace merge)
segment_ids	string[]	No*	Reemplaza todas las memberships existentes. Los IDs de segmentos que no existen en el proyecto se ignoran

*Al menos uno de los tres campos es requerido. Para merge parcial de atributos, ver más en Attributes.

bash

curl -X PUT https://api.reallyquickemails.com/v1/leads/uuid-del-lead \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new@acme.com",
    "data": { "name": "Jane Updated", "plan": "pro" },
    "segment_ids": ["uuid-1"]
  }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.update('uuid-del-lead', {
  email: 'new@acme.com',
  data: { name: 'Jane Updated', plan: 'pro' },
  segment_ids: ['uuid-1'],
});

Response (200):

json

{
  "success": true,
  "lead": {
    "id": "uuid",
    "email": "new@acme.com",
    "data": { "name": "Jane Updated", "plan": "pro" },
    "created_at": "...",
    "updated_at": "...",
    "segment_ids": ["uuid-1"]
  }
}

Errores: si el nuevo email ya existe en otro lead del proyecto, responde 409.

DELETE /v1/leads/:id

Elimina un lead y sus memberships de segmentos.

bash

curl -X DELETE https://api.reallyquickemails.com/v1/leads/uuid-del-lead \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx"

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.delete('uuid-del-lead');

Response (200):

json

{ "success": true }

Segmentos

POST /v1/leads/:id/segments

Agrega un lead a uno o más segmentos.

Campo	Tipo	Requerido	Descripción
segment_ids	string[]	Sí	UUIDs de los segmentos a agregar

bash

curl -X POST https://api.reallyquickemails.com/v1/leads/uuid-del-lead/segments \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "segment_ids": ["uuid-1", "uuid-2"] }'

Response (200):

json

{ "success": true, "added": 2 }

Errores: si algún segmento no existe en el proyecto, responde 404 y no agrega ninguno.

DELETE /v1/leads/:id/segments/:segmentId

Quita un lead de un segmento.

bash

curl -X DELETE https://api.reallyquickemails.com/v1/leads/uuid-del-lead/segments/uuid-del-segmento \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx"

Response (200):

json

{ "success": true }

Errores: si el lead no pertenece al segmento, responde 404.

Campo	Tipo	Requerido	Descripción
tags	string[]	Sí	Tags a agregar

Campo	Tipo	Requerido	Descripción
tags	string[]	Sí	Tags a quitar

Attributes

Atributos custom almacenados en el campo data del lead. Se hace merge (shallow) con los existentes; la clave reservada _tags se preserva. El :email en la ruta debe ir URL-encoded.

POST /v1/leads/:email/attributes

Establece atributos custom en un lead. El body es un objeto JSON plano con los atributos a establecer.

bash

curl -X POST https://api.reallyquickemails.com/v1/leads/jane%40acme.com/attributes \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "pro", "mrr": 49, "team_size": 12 }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.setAttributes('jane@acme.com', { plan: 'pro', mrr: 49, team_size: 12 });

Response (200):

json

{ "success": true, "data": { "plan": "pro", "mrr": 49, "team_size": 12, "name": "Jane" } }

GET /v1/leads/:email/attributes

Devuelve los atributos del lead, excluyendo la clave reservada _tags.

bash

curl https://api.reallyquickemails.com/v1/leads/jane%40acme.com/attributes \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx"

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.leads.getAttributes('jane@acme.com');

Response (200):

json

{ "success": true, "data": { "plan": "pro", "mrr": 49, "team_size": 12, "name": "Jane" } }

Errores

Código	Significado
400	Validación fallida (campo requerido, formato inválido, ID no es UUID)
401	API key inválida o faltante
404	Lead o segmento no encontrado
409	Email ya existe en otro lead del proyecto
500	Error interno

Formato de error:

json

{ "error": "Descripción del error" }

Los errores 500 pueden incluir un campo adicional details con el detalle del error.

Ver más en la guía del SDK de Node.js.

Leads

Autenticacion

Endpoints

POST /v1/leads

GET /v1/leads

GET /v1/leads/:id

PUT /v1/leads/:id

DELETE /v1/leads/:id

Segmentos

POST /v1/leads/:id/segments

DELETE /v1/leads/:id/segments/:segmentId

Tags

POST /v1/leads/:email/tags

DELETE /v1/leads/:email/tags

GET /v1/leads/:email/tags

Attributes

POST /v1/leads/:email/attributes

GET /v1/leads/:email/attributes

Errores