Markdown ↔ HTML

POST /mail/convert converts an email body between markdown and HTML and returns the result immediately — no job, no polling.

Two different conversions. This page is about strings, and it is instant. To convert a file (PDF, Word, spreadsheet, image) into markdown, that is a separate asynchronous job: see Documents to Markdown.

Convert a body

curl -X POST "https://spideriq.ai/api/v1/mail/convert" \
  -H "Authorization: Bearer $SPIDERIQ_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "markdown",
    "to": "html",
    "content": "# Hi\n\nSee the **report**.",
    "mode": "fit"
  }'

content: "<h1>Hi</h1>\n<p>See the <strong>report</strong>.</p>"
from: markdown
to: html
mode: fit
size_original: 31
size_converted: 118

The response echoes from, to and mode back alongside the byte sizes, so you never have to guess what happened to your input.

You declare the formats — nothing is guessed

from and to are both required, and they must differ. SpiderMail never inspects your content to work out which direction you meant.

That is deliberate. Before this endpoint existed, two different parts of the system each guessed at when markdown should become HTML, and they disagreed — so the same body could come out differently depending on how it reached us. Declaring the intent removes the guess.

Modes

::table
mode | Use it when
fit (default) | You want output adapted to its destination. Round-trip stable: markdown → HTML → markdown gives you back what you started with.
raw | You want byte-identical output to what sending and reading already produce — useful for parity checks and migrations.
minimal | You want the smallest faithful output, stripped of anything the destination does not need.

When in doubt, use fit. It is the default because it behaves the way most people expect.

Size limit — it counts bytes, not characters

The limit is 65,536 bytes of UTF-8, and that is a byte count, not a character count. This matters more than it sounds:

• 65,536 plain ASCII characters ≈ 65,536 bytes → accepted

• 40,000 accented or non-Latin characters can be 80,000 bytes → rejected with 413

If you are checking the size before you send, encode the string and measure the buffer. A plain character-length check will let oversized bodies through and then surprise you with a 413.

Errors

::table
Status | Means | Fix
413 | Body is over the 65,536-byte limit | Split the body, or convert less of it. Retrying unchanged will fail identically.
422 | The request did not make sense — `from` is missing, or `from` and `to` are the same | Set both, and make them different. A smaller body will not help.

What it does not touch

This is a pure transform. It reads no mailbox and writes nothing — it never marks a message as read and never changes a stored body. It needs only read access to identify you.

Availability

POST /mail/convert is available over the HTTP API and to marketplace agents. It does not yet have a CLI command or an MCP tool — if you are working through the SpiderIQ CLI or an MCP client, call the endpoint directly for now.