Base de conocimiento
API de correo
Envía un mensaje o cien por llamada, ahora o más tarde, y reintenta sin enviar dos veces.
Detalles
- POST /emails envía un mensaje y POST /emails/batch hasta 100 independientes. Un lote nunca es todo o nada: una dirección errónea en el elemento 7 hace fallar el elemento 7, el resto sale igual y la respuesta informa de cada elemento por separado.
- El contenido sale de una sola fuente: html y/o text, una plantilla guardada por id o slug (fija su versión cuando el texto sea de otra persona) o un borrador existente. Hasta 10 etiquetas viajan con él y se devuelven en cada lectura.
- scheduledAt retiene un mensaje hasta 365 días, como instante ISO 8601 o como duración tipo PT1H. cancellableForSeconds da a un envío inmediato un margen para deshacer de hasta 900 segundos. Ambos se pueden cancelar, y un envío programado reprogramar, hasta que sale.
- Cada envío lleva un Idempotency-Key que se reclama antes de despachar nada, así que un reintento tras un tiempo de espera agotado devuelve el primer resultado con Idempotency-Replayed: true. La misma clave con otro contenido se rechaza como idempotency_key_reuse.
- Cada envío tiene un id msg_ desde el momento en que se acepta. GET /emails/{id} lo lee, /events da el rastro de cada destinatario y /tracking las aperturas y los clics.
- Añade translate y el mensaje se entrega en el idioma del destinatario. Se traduce al aceptar la petición, así que un envío programado lleva el texto que aprobaste, y una traducción que no se puede producir rechaza el envío en lugar de recurrir al original.
- Adjuntos: hasta 20 archivos, los incrustados con un máximo de 5 MB en total. Un archivo mayor se envía indicando el id de un archivo del espacio de trabajo y viaja como enlace de descarga.
- Lo que falta: aún no hay modo de prueba, así que cada clave entrega de verdad, y el registro del envío no tiene estado de rebote. Un rebote se etiqueta en el hilo y se emite como webhook email.bounced, mientras GET /emails sigue mostrando sent.
- La lista de supresión, Direcciones bloqueadas en Ajustes, también está en la API. GET /suppressions la lee con una búsqueda y un filtro por motivo, POST /suppressions bloquea una dirección a mano y DELETE /suppressions/{id} vuelve a permitir una, salvo un rebote permanente, que se queda. El SDK y el servidor MCP hacen lo mismo, y cada cambio dispara el webhook suppression.added o suppression.removed.