Contactos

Los contactos son la base de todo el sistema bulk. Cada contacto tiene un email como identificador único dentro de tu API key, más campos opcionales: name y metadata (un objeto JSON libre para cualquier dato de segmentación que necesites). Un contacto puede estar en múltiples listas y puede tener uno de cuatro estados: active, unsubscribed, bounced o complained.

Esquema

Campo	Tipo	Descripción
`id`	integer	Identificador interno.
`email`	string	Email del contacto. Único por key.
`name`	string	Nombre opcional.
`metadata`	object	Objeto JSON libre para atributos custom.
`status`	string	`active` \| `unsubscribed` \| `bounced` \| `complained`
`key_id`	string	API key a la que pertenece el contacto.
`created_at`	string	Fecha de creación (ISO 8601).
`updated_at`	string	Fecha de última actualización (ISO 8601).

Operaciones

Listar contactos

GET /v1/bulk/contacts

Parámetros de query:

Parámetro	Descripción
`limit`	Máximo de resultados (default: `100`).
`offset`	Desplazamiento para paginación.
`status`	Filtra por estado: `active`, `unsubscribed`, `bounced`, `complained`.
`q` / `search`	Búsqueda por email o nombre.
`key_id`	Filtra por API key (solo admin).
`format`	`csv` para exportar en formato CSV.

Crear o actualizar un contacto

POST /v1/bulk/contacts

Body:

{
  "email": "ana@empresa.com",
  "name": "Ana García",
  "metadata": { "plan": "pro" }
}

Si ya existe un contacto con ese email, sus datos se actualizan. Devuelve 201 con el contacto completo.

Obtener un contacto

GET /v1/bulk/contacts/{email}

Devuelve el contacto con ese email, incluyendo todos sus campos.

Actualizar un contacto

PATCH /v1/bulk/contacts/{email}

Body (todos los campos son opcionales):

{
  "name": "Ana García López",
  "status": "unsubscribed",
  "metadata": { "plan": "enterprise" }
}

Eliminar un contacto

DELETE /v1/bulk/contacts/{email}

Elimina permanentemente el contacto. Devuelve 204 No Content.

Historial de engagement

GET /v1/bulk/contacts/{email}/engagement

Devuelve el historial de campañas recibidas por ese contacto y su score de engagement.

Respuesta:

{
  "email": "ana@empresa.com",
  "sends": [
    {
      "campaign_id": "camp_abc123",
      "campaign_name": "Newsletter Q2",
      "sent_at": "2026-04-15T10:00:00Z",
      "opened": true,
      "clicked": false
    }
  ],
  "totals": {
    "sends": 5,
    "opens": 3,
    "clicks": 1
  },
  "score": "active",
  "last_engagement_at": "2026-04-15T14:22:00Z"
}

El campo score puede ser active, passive o dormant según la actividad reciente del contacto.

Importar contactos en lote

POST /v1/bulk/contacts/import

Body: array de objetos con email (requerido), name y metadata opcionales.

[
  { "email": "ana@empresa.com", "name": "Ana García", "metadata": { "plan": "pro" } },
  { "email": "pedro@cliente.io", "name": "Pedro Sánchez" },
  { "email": "maria@otro.com" }
]

Devuelve 207 Multi-Status con el resultado de cada entrada:

{
  "created": 2,
  "updated": 1,
  "failed": 0,
  "errors": []
}

Pre-chequeo de importación

POST /v1/bulk/contacts/import-preview

Verifica cuántos emails ya existen en tu cuenta antes de hacer el import. No modifica ningún dato.

Body:

{ "emails": ["ana@empresa.com", "nuevo@dominio.com"] }

Respuesta:

{
  "existing": ["ana@empresa.com"],
  "total_unique": 2,
  "total_received": 2
}

Eliminar contactos en lote

POST /v1/bulk/contacts/delete

Eliminación atómica de múltiples contactos. Body:

{ "emails": ["ana@empresa.com", "pedro@cliente.io"] }

Respuesta:

{
  "requested": 2,
  "deleted": 2,
  "not_found": [],
  "forbidden": []
}

Ejemplos

Crear un contacto con metadata

curl -X POST https://api.mailerdash.com/v1/bulk/contacts \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@empresa.com", "name": "Ana García", "metadata": {"plan": "pro", "signup_source": "landing"}}'

Importar contactos en lote

curl -X POST https://api.mailerdash.com/v1/bulk/contacts/import \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"email": "ana@empresa.com", "name": "Ana García", "metadata": {"plan": "pro"}},
    {"email": "pedro@cliente.io", "name": "Pedro Sánchez", "metadata": {"region": "CDMX"}},
    {"email": "maria@otro.com"}
  ]'

Referencia

Para el esquema completo de request/response y códigos de error, consulta la referencia de API bulk.