Listas De Contactos

Gestión de listas de contactos (también llamadas agendas: por eso las rutas viven bajo /agendas/*). Una lista agrupa contactos reutilizables para tus envíos, con nombre, descripción y hasta cuatro etiquetas de campos personalizados.

La clave list_key identifica cada lista y es la que usas en las operaciones de Contactos para agregar, actualizar o consultar sus miembros.

Crear Lista de Contactos
POST /agendas/add
Obtener Listas de Contactos
POST /agendas/get
Renombrar Lista de Contactos
POST /agendas/change_name
Obtener Contactos de Lista
POST /agendas/get_contacts
Eliminar Lista de Contactos
POST /agendas/delete
Buscar Lista de Contactos
GET /contactlist/find

Crear Lista de Contactos

POST https://api.smsmasivos.com.mx/agendas/add
Crea una nueva lista de contactos (agenda). Verifica nombres duplicados

Crea una lista de contactos (agenda) con nombre, descripción y hasta cuatro etiquetas de campos personalizados. El nombre debe ser único dentro de tu cuenta.

La respuesta incluye la list_key que identifica la lista: guárdala, porque es la clave que usan las operaciones de Contactos y el resto de endpoints de listas.

Parameters
agenda_namestringrequerido
Nombre de la lista (debe ser único)
agenda_descriptionstringopcional
Descripción de la lista
custom_field_1stringopcional
Etiqueta del campo personalizado 1
custom_field_2stringopcional
Etiqueta del campo personalizado 2
custom_field_3stringopcional
Etiqueta del campo personalizado 3
custom_field_4stringopcional
Etiqueta del campo personalizado 4

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
agenda_02Falta el nombre de la lista.Envía agenda_name.
agenda_03Ya existe una lista con ese nombre en tu cuenta.Usa un nombre distinto.

El éxito responde agenda_01 con la list_key.

curl -X POST https://api.smsmasivos.com.mx/agendas/add \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "agenda_name": "Clientes VIP",
    "agenda_description": "Lista de clientes frecuentes"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.smsmasivos.com.mx/agendas/add');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'apikey: ' . getenv('SMSMASIVOS_API_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'agenda_name' => 'Clientes VIP',
    'agenda_description' => 'Lista de clientes frecuentes'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
import requests

response = requests.post(
    'https://api.smsmasivos.com.mx/agendas/add',
    headers={
        'Content-Type': 'application/json',
        'apikey': 'TU_API_KEY'
    },
    json={
        'agenda_name': 'Clientes VIP',
        'agenda_description': 'Lista de clientes frecuentes'
    }
)
print(response.json())
const response = await fetch('https://api.smsmasivos.com.mx/agendas/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.SMSMASIVOS_API_KEY
  },
  body: JSON.stringify({
    agenda_name: 'Clientes VIP',
    agenda_description: 'Lista de clientes frecuentes'
  })
});
const data = await response.json();
console.log(data);
const axios = require('axios');

const { data } = await axios.post(
  'https://api.smsmasivos.com.mx/agendas/add',
  {
    agenda_name: 'Clientes VIP',
    agenda_description: 'Lista de clientes frecuentes'
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.SMSMASIVOS_API_KEY
    }
  }
);
console.log(data);
require 'net/http'
require 'json'

uri = URI('https://api.smsmasivos.com.mx/agendas/add')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path, {
  'Content-Type' => 'application/json',
  'apikey' => ENV['SMSMASIVOS_API_KEY']
})
request.body = {
  agenda_name: 'Clientes VIP',
  agenda_description: 'Lista de clientes frecuentes'
}.to_json

response = http.request(request)
puts JSON.parse(response.body)
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "TU_API_KEY");

var payload = new
{
    agenda_name = "Clientes VIP",
    agenda_description = "Lista de clientes frecuentes"
};

var response = await client.PostAsJsonAsync(
    "https://api.smsmasivos.com.mx/agendas/add",
    payload
);
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);
OkHttpClient client = new OkHttpClient();

String json = "{"
    + "\"agenda_name\":\"Clientes VIP\","
    + "\"agenda_description\":\"Lista de clientes frecuentes\""
    + "}";

Request request = new Request.Builder()
    .url("https://api.smsmasivos.com.mx/agendas/add")
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .addHeader("apikey", "TU_API_KEY")
    .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());
Response
{
  "success": true,
  "message": "phoneBookSavedSuccess",
  "status": 200,
  "list_key": "a1b2c3d4e5f6",
  "code": "agenda_01"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Obtener Listas de Contactos

POST https://api.smsmasivos.com.mx/agendas/get
Devuelve todas las listas de contactos del usuario, ordenadas por nombre
curl -X POST https://api.smsmasivos.com.mx/agendas/get \
  -H "apikey: TU_API_KEY"
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.smsmasivos.com.mx/agendas/get');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['apikey: ' . getenv('SMSMASIVOS_API_KEY')]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
import requests
response = requests.post(
    'https://api.smsmasivos.com.mx/agendas/get',
    headers={'apikey': 'TU_API_KEY'}
)
print(response.json())
const response = await fetch('https://api.smsmasivos.com.mx/agendas/get', {
  method: 'POST',
  headers: {'apikey': process.env.SMSMASIVOS_API_KEY}
});
const data = await response.json();
console.log(data);
require 'net/http'; require 'json'
uri = URI('https://api.smsmasivos.com.mx/agendas/get')
http = Net::HTTP.new(uri.host, uri.port); http.use_ssl = true
response = http.request(Net::HTTP::Post.new(uri.path, {'apikey' => ENV['SMSMASIVOS_API_KEY']}))
puts JSON.parse(response.body)
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "TU_API_KEY");
var response = await client.PostAsync("https://api.smsmasivos.com.mx/agendas/get", null);
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
    .url("https://api.smsmasivos.com.mx/agendas/get")
    .post(RequestBody.create(new byte[0]))
    .addHeader("apikey", "TU_API_KEY").build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
Response
{
  "success": true,
  "result": [
    {
      "agenda_name": "Clientes VIP",
      "agenda_description": "Lista de clientes preferentes",
      "agenda_creation_date": "2025-01-15 10:30:00",
      "list_key": "a1b2c3d4e5f6"
    }
  ],
  "status": 200,
  "code": "agendas_01"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Renombrar Lista de Contactos

POST https://api.smsmasivos.com.mx/agendas/change_name
Cambia el nombre de una lista de contactos
Parameters
list_keystringrequerido
Clave de la lista de contactos
agenda_namestringrequerido
Nuevo nombre de la lista

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
change_name_02Falta list_key.Envía la clave de la lista.
change_name_03Falta el nuevo nombre.Envía agenda_name.
err_03La lista no existe.Verifica la list_key con /agendas/get.

El éxito responde change_name_01.

curl https://api.smsmasivos.com.mx/agendas/change_name \
  -d list_key=value \
  -d agenda_name=value
const Listas de Contacto = await sms.listasdecontactos.create({
  list_key: 'value',
  agenda_name: 'value',
})
Listas de Contacto = sms.listasdecontactos.create(
    list_key="value",
    agenda_name="value",
)
Listas de Contacto, err := client.Listasdecontactos.Create(ctx, &sms.ListasDeContactoParams{
    ListKey: sms.String("value"),
    AgendaName: sms.String("value"),
})
Response
{
  "success": true,
  "message": "phonebook_name_updated",
  "status": 200,
  "code": "change_name_01"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Obtener Contactos de Lista

POST https://api.smsmasivos.com.mx/agendas/get_contacts
Obtiene todos los contactos de una lista específica
Parameters
list_keystringrequerido
Clave de la lista de contactos

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
get_contacts_02Falta list_key.Envía la clave de la lista.
err_01La lista no existe.Verifica la list_key con /agendas/get.

El éxito responde get_contacts_01 con todos los contactos de la lista (sin paginación), ordenados por nombre.

curl https://api.smsmasivos.com.mx/agendas/get_contacts \
  -d list_key=value
const Listas de Contacto = await sms.listasdecontactos.create({
  list_key: 'value',
})
Listas de Contacto = sms.listasdecontactos.create(
    list_key="value",
)
Listas de Contacto, err := client.Listasdecontactos.Create(ctx, &sms.ListasDeContactoParams{
    ListKey: sms.String("value"),
})
Response
{
  "success": true,
  "result": [
    {
      "contact_name": "<string>",
      "contact_number": "<string>",
      "contact_email": "<string>",
      "contact_creation_date": "<string>"
    }
  ],
  "status": 200,
  "code": "get_contacts_01"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Eliminar Lista de Contactos

POST https://api.smsmasivos.com.mx/agendas/delete
Elimina una lista de contactos y todos sus contactos

Eliminar una lista elimina también todos sus contactos. La operación no se puede deshacer.

Parameters
list_keystringrequerido
Clave de la lista de contactos

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
get_contacts_02Falta list_key.Envía la clave de la lista.
err_01La lista no existe o no se pudo eliminar.Verifica la list_key con /agendas/get.

El éxito responde delete_01.

curl https://api.smsmasivos.com.mx/agendas/delete \
  -d list_key=value
const Listas de Contacto = await sms.listasdecontactos.create({
  list_key: 'value',
})
Listas de Contacto = sms.listasdecontactos.create(
    list_key="value",
)
Listas de Contacto, err := client.Listasdecontactos.Create(ctx, &sms.ListasDeContactoParams{
    ListKey: sms.String("value"),
})
Response
{
  "success": true,
  "message": "phonebook_name_updated",
  "status": 200,
  "code": "change_name_01"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Buscar Lista de Contactos

GET https://api.smsmasivos.com.mx/contactlist/find
Busca una lista de contactos por nombre (máx. 100 caracteres)
Query parameters
querystringopcional
Texto de búsqueda
curl https://api.smsmasivos.com.mx/contactlist/find
const Listas de Contacto = await sms.listasdecontactos.list()
Listas de Contacto = sms.listasdecontactos.list()
Listas de Contacto, err := client.Listasdecontactos.List(ctx, nil)
Response
{
  "success": true,
  "status": 200,
  "code": "contactlist_03",
  "result": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "total_count": 25,
  "page": 1,
  "total_pages": 3,
  "limit": 10,
  "has_more": true,
  "next_page": 2
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Objeto de respuesta

Estructura de la respuesta que devuelven estos endpoints.

Atributos
successboolean
statusinteger
codestring
Código de respuesta
resultarray<object>
total_countinteger
Número total de resultados
pageinteger
Página actual
total_pagesinteger
Total de páginas
limitinteger
Elementos por página
has_moreboolean
Si hay más páginas disponibles
next_pageinteger | null
Número de la siguiente página (null si es la última)
Objeto de respuesta
{
  "success": true,
  "status": 200,
  "code": "contactlist_03",
  "result": [],
  "total_count": 25,
  "page": 1,
  "total_pages": 3,
  "limit": 10,
  "has_more": true,
  "next_page": 2
}