Documentación para desarrolladores

Primeros pasos

1. Crea una cuenta y una marca, y verifica el dominio desde el que quieres enviar.
2. En la consola crea una API key para esa marca y elige las capacidades que necesita. Las capacidades no se pueden modificar después: para cambiarlas, crea una clave nueva.
3. Llama a la API con la clave en la cabecera Authorization.

Dirección base

https://api.mailronix.com

Autenticación

Authorization: Bearer mrx_live_…

El primer envío

El remitente debe estar en el dominio verificado de la marca a la que está vinculada la clave. La respuesta 202 significa que el mensaje está en cola, no que se haya entregado.

curl -X POST https://api.mailronix.com/email/send \
  -H "Authorization: Bearer mrx_live_<la-tua-chiave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-4821" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Conferma ordine #4821",
    "html_body": "<p>Il tuo ordine #4821 è confermato.</p>"
  }'

El mismo envío en Node.js, sin dependencias:

const risposta = await fetch('https://api.mailronix.com/email/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILRONIX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ordine-4821',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Conferma ordine #4821',
    html_body: '<p>Il tuo ordine #4821 è confermato.</p>',
  }),
})

if (!risposta.ok) {
  const { error } = await risposta.json()
  throw new Error(`${error.code}: ${error.message}`)
}
console.log(await risposta.json()) // { status: 'queued', email_log_id: '…' }

Respuesta

202 Accepted
{ "status": "queued", "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a" }

Para reintentar sin riesgo de duplicados, envía la cabecera Idempotency-Key: una nueva petición con la misma clave y el mismo cuerpo, dentro de las 24 horas, devuelve la respuesta de la primera llamada.

Nombre del remitente, respuestas y adjuntos

Tres campos opcionales de POST /email/send. Quien no los envía obtiene el mismo comportamiento de antes.

Ejemplo con los tres campos

{
  "from": "[email protected]",
  "from_name": "Acme Assistenza",
  "reply_to": "[email protected]",
  "to": "[email protected]",
  "subject": "La tua fattura",
  "html_body": "<p>In allegato la fattura.</p>",
  "attachments": [
    {
      "filename": "fattura-2026-0412.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjcK…"
    }
  ]
}

• from_name: el nombre que lee el destinatario en lugar de la dirección, de 1 a 78 caracteres (los acentos están permitidos; sin @, < >, comillas, saltos de línea ni direcciones web). Si falta, se usa el nombre definido en la marca.
• reply_to: la dirección a la que van las respuestas, en cualquier dominio salvo el de Mailronix. Hay que activarlo en la consola, en los ajustes de la marca, con «Permitir reply_to en la solicitud»: está desactivado por defecto y no se activa con una clave de API, porque una clave robada no debe poder redirigir las respuestas (sin consentimiento la respuesta es 403 reply_to_not_allowed).
• attachments: hasta 5 adjuntos por mensaje, 7 MB de archivos en total y el correo completo por debajo de 10 MB (en el correo los adjuntos pesan aproximadamente un tercio más). Tipos admitidos: PDF, PNG, JPEG, GIF, texto, CSV y calendario. Solo en mensajes transaccionales, en todos los planes: con "marketing": true la respuesta es 400 attachments_not_allowed_for_marketing.
• Los adjuntos permanecen con nosotros solo durante el envío y nunca más de 24 horas; el registro del mensaje conserva nombre, tipo, tamaño y huella, nunca el contenido. No hay análisis antivirus: el contenido es responsabilidad tuya. Para reintentar con la misma Idempotency-Key, vuelve a enviar los mismos bytes.

Qué puede hacer una clave

Cada clave lleva solo las capacidades elegidas al crearla. Sin la capacidad adecuada, la API responde 403 capability_not_granted.

POST /email/send

Envía un correo transaccional, con contenido directo o desde una plantilla con variables.

Capacidad: email:send

GET /email/{id}

Consulta el estado de un envío.

Capacidad: email:read

POST /contacts

Crea un contacto. Nace sin confirmar: la solicitud de confirmación la envía Mailronix.

Capacidad: contacts:write

POST /contacts/revoke

Registra la baja de una dirección.

Capacidad: contacts:unsubscribe

POST /contacts/delete

Elimina un contacto. Requiere también la capacidad de baja.

Capacidad: contacts:delete

GET /contacts/revocations

Lista las revocaciones de la marca de la clave, con cursor.

Capacidad: revocations:read

Reglas que conviene conocer

• Una clave escribe siempre y solo bajo la marca a la que se vinculó al crearla. Si tienes varias marcas, creas una clave por marca.
• Un mensaje es transaccional por defecto. Con "marketing": true solo se envía a contactos que han confirmado su suscripción y lleva el enlace de baja.
• No puedes declarar un consentimiento obtenido en otro lugar: el consentimiento solo vale si el destinatario lo confirma con su propio clic.
• language (opcional, en POST /email/send y POST /contacts): it, en, es, de o fr. Elige el idioma de los textos de servicio y de las páginas enlazadas; no traduce HTML ni plantillas. Sin el campo vale el idioma de la marca; cualquier otro valor produce 400 invalid_language.
• Los errores tienen siempre la misma forma, con un código estable para que lo lea el programa y un mensaje para las personas.
• El límite de peticiones es por clave (429 rate_limited). Agotada la cuota mensual del plan, los envíos se rechazan (403 plan_limit_exceeded) hasta el siguiente mes natural UTC; el plan Free tiene además un límite de 500 destinatarios únicos al día.

{ "error": { "code": "rate_limited", "message": "…" } }

Lo que no se hace por API

Las campañas, la creación y revocación de API keys, las plantillas, la configuración de webhooks y la facturación se gestionan solo desde la consola, con una sesión. Es una decisión de seguridad: una clave robada no debe poder crear credenciales ni redirigir los datos de tus envíos.

Referencia de la API

Cada endpoint, campo y respuesta, generados desde la especificación y legibles sin descargarla.

Especificación OpenAPI

La especificación OpenAPI 3.1 describe cada endpoint, campo y error: impórtala en tu cliente o en tu herramienta de pruebas. Está escrita en italiano.

Webhooks salientes

Para no hacer polling puedes registrar en la consola direcciones HTTPS a las que Mailronix envía los eventos de tu cuenta, con firma HMAC y reintentos automáticos.