Docs
Quickstart
Send a test letter in four steps. Test keys render a real proof and post nothing.
The API is in design. Calls, fields and statuses on this page are illustrative.
1. Connect
Add the server to your MCP client with your test key.
{
"mcpServers": {
"atomside": {
"url": "https://mcp.atomside.com",
"headers": {
"Authorization": "Bearer as_test_..."
}
}
}
}Illustrative. Hosts and field names are not final.
# Send your test key as a bearer token on every request
export ATOMSIDE_KEY=as_test_...
curl https://api.atomside.com/v1/letters/quote \
-H "Authorization: Bearer $ATOMSIDE_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": { ... }, "content_markdown": "...", "class": "second" }'Illustrative. Hosts and field names are not final.
// Node 18 or later. No SDK needed: send your test key as a bearer token.
const res = await fetch('https://api.atomside.com/v1/letters/quote', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ATOMSIDE_KEY}`, // as_test_...
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: { /* ... */ }, content_markdown: '...', class: 'second' }),
});
const quote = await res.json();Illustrative. Hosts and field names are not final.
# Python 3 with requests. Send your test key as a bearer token.
import os, requests
res = requests.post(
"https://api.atomside.com/v1/letters/quote",
headers={"Authorization": f"Bearer {os.environ['ATOMSIDE_KEY']}"}, # as_test_...
json={"to": {...}, "content_markdown": "...", "class": "second"},
)
quote = res.json()Illustrative. Hosts and field names are not final.
2. Get a quote
The quote checks the address, renders the letter and returns a price. Open the proof to see exactly what will print.
quote_letter({ "to": { ... }, "content_markdown": "...", "class": "second" })3. Send it
Pass the quote and an idempotency key. Calling again with the same key returns the same letter.
send_letter({ "quote": "qt_...", "idempotency_key": "..." })Held for approval? If the key requires approval, the status is awaiting_approval until someone approves by email.
4. Check status
get_letter({ "letter": "ltr_..." })| Status | Meaning |
|---|---|
awaiting_approval | Waiting for a person |
submitted | Accepted by the printer |
printed | Printed and enveloped |
dispatched | Handed to Royal Mail |
failed | Not sent; credits returned to your balance |
Ready for real letters?Verify your sender address and go live