TrackMailer — Documentación

Getting Started

1. Crea y verifica una única cuenta de Cloud. 2. Selecciona o crea la organización propietaria de la integración. 3. Crea un proyecto para el sitio, tienda o marca cuyos datos deban permanecer juntos. 4. Abre el espacio del producto y confirma que está habilitado antes de copiar credenciales o enviar tráfico de producción.

Con esto termina la configuración de la cuenta. Las secciones siguientes son guías de implementación. Las credenciales siempre pertenecen a un proyecto; los secretos de servidor nunca deben aparecer en código del navegador, repositorios públicos ni variables del cliente.

Antes de integrar

El envío transaccional solo está disponible para organizaciones habilitadas con suscripción o autorización de servicio activa, dominio remitente verificado y clave Live activa. Las escrituras de contactos requieren contacts:write. Sandbox valida los mismos contratos del proyecto sin guardar contactos ni entregar correo.

Crear y guardar una clave API

Abre TrackMailer → Claves API en Cloud. Un propietario o administrador selecciona Sandbox o Live, los scopes mínimos, los dominios remitentes permitidos y una vigencia de 1–365 días. El token completo se muestra una vez; guárdalo en el gestor de secretos del servidor que hará las llamadas.

Define TRACKMAILER_API_URL como https://us-east4-markengroup-cloud-services.cloudfunctions.net/trackmailerApi. Usa contacts:write para importar contactos, transactional:send para entrega transaccional y sequences:enroll solo para validar el contrato porque la ejecución de secuencias aún no está activa. Para rotar, crea el reemplazo, despliégalo, verifica el tráfico y revoca la clave anterior. La API usa Authorization: Bearer <token> y JSON.

Crear o actualizar un contacto

Envía la operación contacts.upsert por POST a $TRACKMAILER_API_URL/v1/requests. Una clave Live guarda el contacto del proyecto; una clave Sandbox devuelve status=validated, sent=false y persisted=false. El email identifica al contacto dentro del proyecto y externalId puede guardar la ID estable del sistema origen.

Attributes debe coincidir con campos definidos previamente en el espacio. Consent requiere estado, fuente y fecha ISO 8601 no futura. Una respuesta Live correcta contiene status=stored, contactId y revision.

curl --request POST "$TRACKMAILER_API_URL/v1/requests" \
  --header "Authorization: Bearer $TRACKMAILER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "operation": "contacts.upsert",
  "contact": {
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "externalId": "crm_123",
    "attributes": {},
    "listIds": [
      "LIST_ID"
    ],
    "consent": {
      "status": "subscribed",
      "source": "checkout",
      "recordedAt": "2026-09-08T15:00:00Z"
    }
  }
}'

Añadir o quitar de una lista

Crea la lista manual en TrackMailer → Audiencias → Grupos y copia la ID mostrada. Inclúyela en contacts.upsert para añadir el contacto. La operación API es aditiva: listIds posteriores se combinan con las membresías existentes y un array vacío no elimina listas anteriores.

Quitar un contacto de una o varias listas es actualmente una operación del panel: abre el contacto, desmarca los grupos y guarda. Todavía no existe un endpoint público para reemplazar membresías o quitar de una lista; una integración no debe asumir que contacts.upsert elimina membresías.

Baja y supresión

Para registrar una baja desde tu centro de preferencias, envía contacts.upsert con consent.status=unsubscribed, la fuente y el momento. Esto suprime el contacto y no equivale simplemente a quitarlo de una lista. Los contactos ya dados de baja, rebotados o denunciados nunca se reactivan con una importación posterior.

curl --request POST "$TRACKMAILER_API_URL/v1/requests" \
  --header "Authorization: Bearer $TRACKMAILER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "operation": "contacts.upsert",
  "contact": {
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "attributes": {},
    "listIds": [],
    "consent": {
      "status": "unsubscribed",
      "source": "preference-center",
      "recordedAt": "2026-09-08T16:00:00Z"
    }
  }
}'

Preparar un dominio remitente

El espacio de trabajo acepta automáticamente el dominio del correo de acceso verificado y sus subdominios; la configuración no requiere aprobación del administrador de la plataforma. Añade el hostname exacto, como mail.example.com, en TrackMailer → Dominios remitentes. Publica el TXT de propiedad del proyecto y los registros DKIM, MAIL FROM MX y SPF mostrados; espera la verificación completa. Usa la senderDomainId de 64 caracteres mostrada en las claves y solicitudes.

Usa un subdominio dedicado por marca o flujo relevante. Cada host remitente sigue necesitando su propia prueba del proyecto y verificación completa; una clave solo puede enviar mediante senderDomainIds asociadas explícitamente.

Anti-Spam Health: DKIM, SPF y DMARC

TrackMailer muestra preparación del dominio, autenticación y señales de entrega. Copia los valores DNS exactamente y coordina DMARC con la administración de correo. La autenticación reduce problemas evitables, pero no garantiza la bandeja de entrada.

Enviar un email transaccional

Haz POST desde un servidor de confianza a $TRACKMAILER_API_URL/v1/email/send. La clave Live necesita transactional:send y debe permitir la senderDomainId elegida. La solicitud admite 1–20 destinatarios únicos, HTML y texto plano, reply-to opcional y los propósitos receipt, security o notification.

Define un header Idempotency-Key único de 8–128 caracteres para el mensaje lógico. Repetir la misma clave y body devuelve la misma messageId sin otra entrega; cambiar el contenido con la misma clave devuelve HTTP 409 idempotency_conflict. Una nueva solicitud aceptada devuelve HTTP 202 con status=queued.

curl --request POST "$TRACKMAILER_API_URL/v1/email/send" \
  --header "Authorization: Bearer $TRACKMAILER_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order_8472_confirmation_v1" \
  --data '{
  "senderDomainId": "SENDER_DOMAIN_ID",
  "fromLocalPart": "orders",
  "fromName": "Example Shop",
  "to": [
    {
      "email": "alex@example.com",
      "name": "Alex Rivera"
    }
  ],
  "replyTo": {
    "email": "support@example.com",
    "name": "Support"
  },
  "subject": "We received your order",
  "html": "<p>Thanks for your order.</p>",
  "text": "Thanks for your order.",
  "purpose": "receipt",
  "tags": {
    "MessageType": "order_confirmation",
    "Environment": "production"
  }
}'

Validar antes de enviar

Usa una clave Sandbox contra /v1/requests para contacts.upsert, transactional.send o sequence.enroll. Sandbox valida esquema, scope y recursos del proyecto, pero no guarda, envía ni inscribe. El endpoint productivo /v1/email/send siempre exige una clave Live.

Respuestas, estados y reintentos

Guarda requestId y messageId de cada envío aceptado. Consulta Envíos en TrackMailer para distinguir queued, sent, delivered, bounced, complained, suppressed, failed o uncertain. HTTP 202 significa encolado de forma duradera, no entregado ni garantizado en la bandeja.

Reintenta 429 después del valor Retry-After. Reintenta errores 503 transitorios con backoff exponencial limitado, misma clave de idempotencia y mismo body. No reintentes 400, 401, 403, 402 o 409 hasta corregir validación, clave, scope, remitente, permiso, facturación o conflicto.