Envío y seguimiento de correo

El espacio de nombres emails es la API de envío en forma de comandos, uno por cada método de openemail.emails en el SDK. Cada uno llama a un endpoint y muestra lo que devuelve. El espacio de nombres tracking lee las aperturas y los clics del correo que enviaste. openemail email funciona en lugar de openemail emails.

Cada comando de esta página necesita un inicio de sesión, con el navegador o con una clave de API, y uno de dos scopes: emails:send para enviar, traducir, cancelar y reprogramar, y emails:read para todo lo que solo lee.

openemail send es el comando escrito a mano de la página Correo, y envía a través de emails send. Está hecho para una persona ante un terminal: elige la dirección de envío cuando omites --from, lee el cuerpo de un archivo, de stdin o de tu editor, adjunta archivos por ruta y muestra un resumen para confirmar antes de que salga nada. openemail emails send recibe el cuerpo de la solicitud como opciones, una por campo, y no pregunta nada, lo que va bien para un script que sabe exactamente lo que envía.

Solo emails send tiene --tracking para desactivar las aperturas o los clics en un envío, --signature, --headers para cabeceras personalizadas, --attachment-delivery para elegir entre adjuntar archivos o enlazarlos, y --data para el cuerpo entero como JSON, en línea, desde un archivo con @path o desde stdin con -.

send, send-batch, translate, cancel y reschedule necesitan emails:send. list, get, list-events y get-tracking necesitan emails:read. Un id de correo es msg_ seguido de 24 caracteres hexadecimales, tal como lo devuelve un envío.

Los cinco necesitan emails:read. tracking get, list-opens y list-clicks aceptan cualquiera de los dos ids que tiene un mensaje: el id msg_ que devolvió su envío, o el id de seguimiento tmsg_ que llevan tracking list y los payloads de los webhooks.

tracking list y get-stats cubren cada mensaje con seguimiento que envió el buzón, incluido el correo escrito en la app web y el enviado por las herramientas MCP o el asistente, mientras que emails list contiene los registros de envío que hizo la API. Un informe sin registro de envío tiene sendId con el valor null.

Envía desde un script con una clave de idempotencia propia. Volver a ejecutarlo con la misma --idempotency-key muestra el primer correo con replayed: true en lugar de enviar un segundo.

openemail emails send \  --from 'Acme Billing <[email protected]>' \  --to [email protected] \  --subject 'Your September invoice' \  --html '<p>The invoice is attached. Tell me if anything on it looks wrong.</p>' \  --attachments '[{"fileId":"file_6bb640f5b99e47deb758f1f5"}]' \  --tracking '{"opens":false}' \  --idempotency-key invoice:inv_2026_09_4192 \  --json | jq -r '.id + " " + .status'

Haz que una persona lea una traducción antes de que salga. Envía el texto aprobado como --subject y --html normales, sin --translate, o se traducirá una segunda vez. El html traducido ya contiene tu original debajo, salvo que pases --no-include-original.

openemail emails translate --to de \  --subject 'Your September invoice' \  --html "$(cat invoice.html)" \  --json > preview.jsonjq -r .html preview.jsonopenemail emails send --from [email protected] --to [email protected] \  --subject "$(jq -r .subject preview.json)" \  --html "$(jq -r .html preview.json)"

Envía un lote desde un archivo. El comando sale con el código 0 siempre que el lote se haya procesado, aunque fallen algunos elementos, así que lee failed y el status de cada elemento. Volver a ejecutarlo con la misma clave reproduce los elementos que salieron y envía solo el resto, siempre que el array mantenga su orden.

[  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4192", "text": "Thanks for your order." },  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4193", "text": "Thanks for your order." }]

openemail emails send-batch receipts.json --idempotency-key receipts:2026-09-27 --json > result.jsonjq '{ sent, failed }' result.jsonjq -r '.items[] | select(.status == "error") | "\(.index) \(.error.code)"' result.json

Programa un correo, muévelo y cancélalo. --yes responde a la confirmación que pide cancel, algo que un script no puede hacer.

ID=$(openemail send --from [email protected] --to [email protected] --subject "Standup notes" \  --body-file notes.md --at 2026-10-01T09:00:00Z --json | jq -r .id)openemail emails reschedule "$ID" 2026-10-01T13:00:00Zopenemail emails get "$ID" --json | jq -r '.status + " " + .scheduledAt'openemail emails cancel "$ID" --yes

Busca los envíos que fallaron y lee qué le pasó a uno. Redirigido sin --json, --all muestra un objeto JSON por línea.

openemail emails list --status failed,partial --from [email protected] --all | jq -r .idopenemail emails get msg_3f9a1c07d2b84e6a9c5b1f20openemail emails list-events msg_3f9a1c07d2b84e6a9c5b1f20 --all --json | jq -r '.items[] | .createdAt + " " + .type'

Lee una semana de interacción en días que cortan a medianoche UTC+2, lista lo que nadie abrió y cuenta los clics en cada enlace de un mensaje.

openemail tracking get-stats --days 7 --offset-minutes 120 --json | jq '{ tracked, openRate, clickRate }'openemail tracking list --no-opened --days 7 --all | jq -r .subjectopenemail tracking list-clicks msg_3f9a1c07d2b84e6a9c5b1f20 --all | jq -r .url | sort | uniq -c

• —Un inicio de sesión con el navegador pide los scopes en la página de aprobación, y openemail login --scopes emails:send,emails:read preselecciona ambos. Un comando al que le falta su scope se detiene con el código de salida 4 e insufficient_scope, y nombra el scope.
• —send --attach con más de 5 MB de archivos los sube primero a Archivos, lo que también necesita files:write.
• —Ninguno de estos comandos pide un código de verificación, así que un inicio de sesión con el navegador los ejecuta igual que una clave de API.
• —emails cancel pregunta antes de cancelar, y --yes responde por ti. Sin supervisión y sin --yes, se detiene con Refusing to run unattended. Pass --yes to confirm. y el código de salida 2.
• —emails send, send-batch y reschedule nunca preguntan. send muestra un resumen y pregunta solo en un terminal, y --yes también se lo salta.
• —--dry-run muestra la solicitud que enviaría un comando, no envía nada y sale con el código 0. En emails translate no consume ninguna acción de IA, y en emails cancel no pregunta nada.

emails list, emails list-events, tracking list, list-opens y list-clicks leen una página. --limit fija su tamaño, de 1 a 100 con 25 por defecto para las dos listas de emails, y de 1 a 200 con 50 por defecto para las tres listas de tracking. --cursor sigue desde el cursor que mostró una página.

• —--all lee todas las páginas y transmite los elementos: una tabla en un terminal, y un objeto JSON por línea cuando se redirige o con --ndjson.
• —--max <n> se detiene tras esa cantidad de elementos, e implica --all.
• —--json muestra un único documento { items, hasMore, nextCursor }, también con --all.
• —La paginación es por cursor, no por desplazamiento, así que el correo enviado mientras paginas nunca desplaza ni repite una fila.

• —Cada ejecución crea su propia clave de idempotencia, que cubre los reintentos dentro de esa ejecución. Ejecutar un envío dos veces envía dos veces, salvo que ambas ejecuciones pasen la misma --idempotency-key. La misma clave con un cuerpo distinto se rechaza con idempotency_key_reuse y el código de salida 7.
• —Solo el correo queued y scheduled se puede cancelar o mover. Un envío inmediato sin ventana para deshacer sale dentro de la propia solicitud, así que cuando tienes su id suele ser demasiado tarde, y la llamada termina con email_not_cancellable y el código de salida 6.
• —Un correo cancelado sigue cancelado. Reprogramar cambia solo la hora, contada desde que el servidor recibe la solicitud en el caso de una duración, así que para cambiar el texto, cancela y vuelve a enviar.
• —Una traducción que no se puede producir rechaza el envío entero, y nada sale sin traducir. Un lote traducido contiene como máximo 10 mensajes que llevan translate.
• —Una cuota de envío agotada detiene un envío con send_quota_exceeded hasta el primer día del mes, y una cuota de IA agotada detiene una traducción con ai_quota_exceeded hasta la medianoche UTC, ambas con el código de salida 8.
• —El correo enviado con una clave oe_test_ nunca se entrega. Aparece como sent, con transport en test, y nunca tiene seguimiento.
• —emails get-tracking y tracking get responden 404, código de salida 5, para un mensaje que no llevaba píxel ni enlaces reescritos, porque sin seguimiento no es lo mismo que sin abrir. El seguimiento sigue la configuración con la que se envió el mensaje, así que activarlo más tarde no alcanza al correo anterior.
• —Cada recuento es un mínimo. Un lector cuyo cliente de correo bloquea las imágenes nunca cuenta como apertura, y un clic es una prueba de lectura más fuerte que una apertura.
• —list-opens y list-clicks responden 404 para un id msg_ sin nada con seguimiento, pero aceptan un id tmsg_ tal cual, así que uno desconocido vuelve como una lista vacía.
• —Una clave limitada a algunas direcciones solo ve el correo enviado desde esas direcciones, y una que tiene un dominio entero cubre todas sus direcciones.

Esta página nombra las opciones más importantes. openemail <command> --help lista cada argumento y opción que acepta un comando, con su tipo, el scope que necesita, su método y ruta, lo que devuelve y las notas de la referencia de la API. Añade --json para obtener la misma ayuda como un único documento JSON.

openemail emails --helpopenemail emails send --helpopenemail tracking list-opens --help --json