Excluir a un contacto de un tema

POST /api/v1/contacts/{contactId}/topics/{topicId}/opt-out Hace que un contacto deje de recibir los mensajes asignados a un tema. El contacto sigue suscrito a la lista y puede seguir recibiendo mensajes de todos los demás temas.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 403
Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Parámetros de ruta

ParámetroTipoDescripción
contactIdstringObligatorio. Identificador del contacto
topicIdstringObligatorio. Identificador del tema que se deja de enviar

Ejemplo

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/contacts/$CONTACT_ID/topics/$TOPIC_ID/opt-out"

Respuesta

  • 200 OK: la preferencia del tema es opted_out, también cuando ya lo era.
  • 400 Bad Request: un identificador de la ruta no es un UUID válido; details identifica el campo.
  • 401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
  • 403 Forbidden: el propietario de la clave es member, no admin.
  • 404 Not Found: el contacto o el tema no existe, pertenece a otra organización, o los dos recursos no pertenecen a la misma organización.
  • 429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

CampoTipoDescripción
successbooleanIndica si la operación se realizó correctamente
data.contactIdstringIdentificador del contacto
data.topicIdstringIdentificador del tema
data.statusstringSiempre opted_out

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "contactId": "4d19c0a2-8f20-4fb8-9d55-39a88f86d778",
    "topicId": "a338c425-3115-4890-a01c-f2f6f012db93",
    "status": "opted_out"
  }
}

Notas

  • La llamada es idempotente. Repetirla no crea otra preferencia ni cambia la fecha de exclusión original.
  • Esta llamada nunca cambia el estado de suscripción global del contacto.

Relacionado