SendLetter MCP server
Commit Sep 6, 2026Sends real, printed letters by post across Europe using text, rich text, or PDF files.
Also known as gertsnijder/sendletter-node, sendletter-node
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Sep 6, 2026
- License
- MIT
What is SendLetter MCP?
SendLetter sends real, printed letters by post across Europe using text, rich text, or PDF files.
Summary generated from the project's README
About SendLetter MCP server
SendLetter allows developers to send physical, printed letters through the mail across Europe using Node.js. The service handles the entire process of printing, folding, franking, and posting documents. Users can provide content as plain text, rich text, or files such as PDFs via base64 encoding or URLs. This tool is designed for developers building automated mailing systems, such as those sending invoices or reminders.
To use the service, you must provide a SendLetter API key. The system includes a dedicated test mode using keys starting with sk_test_, which allows you to simulate the full lifecycle from submission to delivery without incurring charges or printing actual paper. The server supports different shipping products including standard, priority, and registered mail, with options for color printing. It also provides tools to validate recipient addresses and get quotes before finalizing a shipment.
What you can do with it
- 1Automate physical invoice deliverySend a PDF invoice as a registered letter to a customer's physical address.
- 2Verify mailing addressesCheck if a recipient's address is valid before attempting to send a letter.
- 3Simulate mail workflowsTest the entire mailing status chain without spending money or printing real letters.
- 4Track delivery status via webhooksReceive automated updates when a letter is printed, posted, or delivered.
Written from the project's README. Every use case is checked against a quote from it.
How to install SendLetter MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SendLetter MCP in Claude Code
$ claude mcp add --transport http sendletter-node https://sendletter.eu/api/mcpInstall SendLetter MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sendletter-node": {
"url": "https://sendletter.eu/api/mcp"
}
}
}Install SendLetter MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sendletter-node": {
"type": "http",
"url": "https://sendletter.eu/api/mcp"
}
}
}Install SendLetter MCP in VS Code CLI
$ code --add-mcp '{"name":"sendletter-node","type":"http","url":"https://sendletter.eu/api/mcp"}'Install SendLetter MCP in Codex
$ codex mcp add sendletter-node --url https://sendletter.eu/api/mcpInstall SendLetter MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sendletter-node] url = "https://sendletter.eu/api/mcp"
Install SendLetter MCP in Gemini CLI
$ gemini mcp add -s user --transport http sendletter-node https://sendletter.eu/api/mcpInstall SendLetter MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sendletter-node": {
"url": "https://sendletter.eu/api/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegertsnijder/sendletter-node is public and reachablegithub.com/gertsnijder/sendletter-node ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-06github.com/gertsnijder/sendletter-node ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubsendletter
Send a real letter — printed, folded, franked and handed to the post — from Node.
npm install sendletter
import { SendLetter } from 'sendletter'
const sendletter = new SendLetter(process.env.SENDLETTER_API_KEY!)
const input = {
idempotencyKey: 'invoice-2026-0042-reminder-1',
sender: {
company: 'Twilper',
name: 'Gert Snijder',
street: 'Merelstraat',
number: '64',
postalCode: '8916 AX',
city: 'Leeuwarden',
country: 'NL',
},
recipient: {
name: 'Jan de Vries',
street: 'Keizersgracht',
number: '123',
postalCode: '1015 CJ',
city: 'Amsterdam',
country: 'NL',
},
text: 'Beste heer De Vries,\n\nBijgaand de herinnering voor factuur 2026-0042.',
}
const prepared = await sendletter.prepare(input)
console.log(prepared.id, prepared.pages, prepared.totalCents)
const pdf = await sendletter.download(prepared.id)
Show the PDF and exact total to the user. After approval, use the same input and key:
const letter = await sendletter.send({ ...input, expectedTotalCents: prepared.totalCents })
console.log(letter.id, letter.status, letter.totalCents)
Get a key at sendletter.eu. Keys starting
sk_test_ post nothing, charge nothing, and still run the whole status chain, so
you can build against the real thing.
Sending
Give the content exactly one way: text, document (rich text), file
(base64) or fileUrl. Two is refused rather than guessed at, because the wrong
document in a postbox cannot be recalled.
// An invoice you already have as a PDF.
await sendletter.send({
sender,
recipient,
file: { name: 'invoice.pdf', contentBase64: pdf.toString('base64') },
product: 'registered', // 'standard' | 'priority' | 'registered'
colour: true,
idempotencyKey: `invoice-${invoice.id}`,
})
Send an idempotencyKey on anything that can be retried. A repeat with the
same key returns the original letter instead of a second envelope. That single
field is what makes a retry after a network timeout safe, and a timeout says
nothing about whether the letter was accepted.
Reading
await sendletter.get(id) // one letter
await sendletter.list({ status: 'posted' }) // one page
await sendletter.cancel(id, 'order withdrawn') // while it is still cancellable
await sendletter.download(id) // the PDF as printed
await sendletter.download(id, { proof: true }) // proof of posting
for await (const letter of sendletter.all({ mode: 'live' })) {
// walks every page; you never hold the cursor
}
Invoices and credit notes
Every paid live letter receives its invoice number at payment time. Test letters never consume the statutory series. A full refund keeps that invoice and adds a separately numbered negative credit note.
const page = await sendletter.listInvoices()
await writeFile('invoice.pdf', await sendletter.downloadInvoice(page.data[0].id))
if (page.data[0].creditNote) {
await writeFile(
'credit-note.pdf',
await sendletter.downloadCreditNote(page.data[0].creditNote.id),
)
}
Checking before you spend
const check = await sendletter.validateAddress(recipient)
if (!check.valid) console.log(check.problems) // answers, does not throw
const quote = await sendletter.quote({ destination: 'DE', pages: 3 })
validateAddress returns a bad address rather than throwing: a wrong postcode
is the successful outcome of asking. supported: false is the one that cannot
be fixed by editing the address — we do not carry to that country.
Errors
Everything the API refuses becomes a SendLetterError with a code to branch
on.
import { SendLetterError } from 'sendletter'
try {
await sendletter.send({ sender, recipient, text })
} catch (error) {
if (!(error instanceof SendLetterError)) throw error
if (error.code === 'insufficient_balance') {
// Put this in front of the customer; the wallet is short, nothing else.
return redirect(error.topUpUrl!)
}
if (error.isRetryable) {
await sleep((error.retryAfter ?? 5) * 1000)
}
}
isRetryable covers 429 and 5xx. Nothing else should be retried: a 400 means
the letter will be refused just as firmly the second time.
Webhooks
Status changes arrive as a POST to the URL you registered. Verify them. Without that, anyone who learns your endpoint can tell your system a letter was delivered.
import { verifyWebhook, SendLetterError } from 'sendletter'
export async function POST(request: Request) {
const rawBody = await request.text() // the raw text, not the parsed object
let event
try {
event = verifyWebhook({
rawBody,
signature: request.headers.get('x-sendletter-signature'),
secret: process.env.SENDLETTER_WEBHOOK_SECRET!,
})
} catch (error) {
if (error instanceof SendLetterError) return new Response('nope', { status: 400 })
throw error
}
if (await alreadyHandled(event.id)) return new Response('ok') // see below
await handle(event) // letter.posted, ...
return new Response('ok')
}
Two things this shape gets right and hand-rolled verification usually does not:
- The raw body, not a re-serialised one. The signature covers the exact
bytes we sent, and
JSON.stringifydoes not promise to reproduce them. Read the body as text, verify, then parse. - Deduplicate on
event.id. Delivery is at-least-once with retries, so a timeout on your side means the same event arrives again.letter.postedhandled twice should not bill a customer twice.
Events: letter.submitted, letter.printed, letter.posted,
letter.delivered, letter.failed, letter.refunded.
Test mode
A sk_test_ key runs the full chain — submitted → printed → posted → delivered — with webhooks firing exactly as they will in production, while
touching no wallet and no printer. client.isTestMode tells you which kind of
key you are holding, which is worth asserting in a deploy check: the two look
alike in a log and only one of them costs money.
Reference
sendletter.eu/en/developers ·
OpenAPI at /api/v1/openapi.json · MIT
SendLetter MCP questions
How do I add SendLetter MCP to Claude Code?
Run claude mcp add --transport http sendletter-node https://sendletter.eu/api/mcp in your terminal. Add --scope user to make it available in every project.
How do I add SendLetter MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How can I test the service without being charged?
You can use a test key starting with sk_test_ which runs the full status chain without charging your account or printing anything.
What formats can I use to send content?
You can provide content as plain text, rich text (document), a base64 encoded file, or a file URL.
Can I verify if an address is correct before sending?
Yes, the service provides a validation method that returns address problems instead of throwing an error.
How do I prevent duplicate letters if a network request fails?
Use an idempotency key on retriable requests; a repeat with the same key will return the original letter instead of creating a new one.