Developer documentation

Getting started

1. Create an account and a brand, then verify the domain you want to send from.
2. In the console, create an API key for that brand and choose the capabilities it needs. Capabilities cannot be changed later: to change them, create a new key.
3. Call the API with the key in the Authorization header.

Base URL

https://api.mailronix.com

Authentication

Authorization: Bearer mrx_live_…

Your first send

The sender must be on the verified domain of the brand the key is bound to. A 202 response means the message is queued, not that it has been delivered.

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>"
  }'

The same request in Node.js, with no dependencies:

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: '…' }

Response

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

To retry without risking duplicates, send the Idempotency-Key header: a new request with the same key and the same body within 24 hours returns the response of the first call.

Sender name, replies and attachments

Three optional fields of POST /email/send. If you leave them out, behaviour is the same as before.

Example with the three fields

{
  "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: the name the recipient sees instead of the address, 1 to 78 characters (accents are fine; no @, < >, quotes, line breaks or web addresses). If omitted, the name set on the brand is used.
• reply_to: the address replies go to, on any domain except Mailronix's own. It must be enabled in the console, in the brand settings, with "Allow reply_to in the request": it is off by default and cannot be switched on with an API key, because a stolen key must not be able to redirect replies (without consent the response is 403 reply_to_not_allowed).
• attachments: up to 5 attachments per message, 7 MB of files in total and the complete email under 10 MB (in email, attachments weigh about a third more). Allowed types: PDF, PNG, JPEG, GIF, text, CSV and calendar. Transactional messages only, on every plan: with "marketing": true the response is 400 attachments_not_allowed_for_marketing.
• Attachments stay with us only while the message is being sent and never longer than 24 hours; the message log keeps name, type, size and fingerprint, never the content. There is no antivirus scan: the content is your responsibility. To retry with the same Idempotency-Key, send the same bytes again.

What a key can do

Each key carries only the capabilities chosen when it was created. Without the right capability the API answers 403 capability_not_granted.

POST /email/send

Send a transactional email, with direct content or from a template with variables.

Capability: email:send

GET /email/{id}

Read the status of a send.

Capability: email:read

POST /contacts

Create a contact. It starts unconfirmed: the confirmation request is sent by Mailronix.

Capability: contacts:write

POST /contacts/revoke

Record an address's unsubscription.

Capability: contacts:unsubscribe

POST /contacts/delete

Delete a contact. It also requires the unsubscribe capability.

Capability: contacts:delete

GET /contacts/revocations

List the revocations of the key's brand, cursor-paginated.

Capability: revocations:read

Rules to know

• A key always writes under the one brand it was bound to when created. If you have several brands, create one key per brand.
• A message is transactional by default. With "marketing": true it is sent only to contacts who confirmed their subscription, and carries the unsubscribe link.
• You cannot declare consent collected elsewhere: consent counts only when the recipient confirms it with their own click.
• language (optional, on POST /email/send and POST /contacts): it, en, es, de or fr. It selects the language of the service texts and linked pages; it does not translate HTML or templates. Without the field the brand's language applies; any other value returns 400 invalid_language.
• Errors always have the same shape, with a stable code for programs to read and a message for people.
• The request limit is per key (429 rate_limited). Once the plan's monthly quota is used up, sends are rejected (403 plan_limit_exceeded) until the next UTC calendar month; the Free plan also has a limit of 500 unique recipients per day.

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

What is not done through the API

Campaigns, creating and revoking API keys, templates, webhook configuration and billing are managed only from the console, with a session. This is a security choice: a stolen key must not be able to create credentials or redirect the data of your sends.

API reference

Every endpoint, field and response, generated from the specification and readable without downloading it.

OpenAPI specification

The OpenAPI 3.1 specification describes every endpoint, field and error: import it into your client or testing tool. It is written in Italian.

Outgoing webhooks

To avoid polling, you can register HTTPS addresses in the console to which Mailronix sends your account's events, with an HMAC signature and automatic retries.