Connettore MCP

Spedire una lettera dal proprio assistente IA

Basta aggiungere un URL a Claude, ChatGPT o qualsiasi client MCP. L'assistente prepara il documento originale per la stampa su A4 e la spedizione tracciata con Australia Post. L'anteprima si controlla e si paga sul nostro sito, quindi nulla viene spedito senza il proprio intervento.

$10 posta ordinaria$20 Express Post

URL del server

https://unopost.com.au/api/mcp

Gli stessi prezzi del sito, GST inclusa. Niente account, accesso o chiave API.

Spedisci dal tuo codice? Il connettore funziona con qualsiasi client MCP o con semplice HTTP, ma ogni lettera si paga sul nostro sito. Per spedire senza l'intervento di nessuno, usa l'API x402.

Collegarlo Scheda del server

Collegarlo

Il connettore è un server MCP remoto su Streamable HTTP. Non richiede l'accesso, quindi lasciare disattivata l'autenticazione.

Claude: aprire Customize → Connectors, scegliere Add custom connector, chiamarlo Unopost e incollare l'URL del server. In una chat, attivare Unopost dal menu degli strumenti.
ChatGPT: aggiungere un connettore personalizzato in modalità sviluppatore con l'URL del server e senza autenticazione, poi attivarlo nella chat.
Claude Code e altri client: aggiungerlo come server HTTP remoto. Qualsiasi client che accetta server MCP personalizzati usa lo stesso URL.

Claude Code

claude mcp add --transport http unopost https://unopost.com.au/api/mcp

.mcp.json

{
  "mcpServers": {
    "unopost": {
      "type": "http",
      "url": "https://unopost.com.au/api/mcp"
    }
  }
}

L'assistente conferma gli indirizzi con l'utente, prepara la lettera e gli fornisce un link privato per la revisione. Lì l'utente controlla l'anteprima, inserisce un'email e paga con carta. È il pagamento a far spedire la lettera.

Cosa dice l'utente

Post this letter by Express Post to Jane Citizen,
12 Example Street, Southbank VIC 3006.
My return address is 1 Sample Road, Carlton VIC 3053.

Strumenti

Gli assistenti li chiamano da soli. Ogni risultato di prepare_letter, finish_letter_upload e get_letter_status contiene reviewUrl, la pagina privata in cui l'utente controlla l'anteprima e paga, e instructions, che indicano cosa dire poi all'utente.

TOOLget_letter_infoPrezzi, limiti, orari di spedizione, consegna, tracciamento e annullamento.TOOLprepare_letterPrende il file allegato dall'utente e avvia una lettera.TOOLcreate_letter_uploadRiserva una lettera e restituisce un link a cui caricare il file.TOOLfinish_letter_uploadIndirizza una lettera caricata e ne avvia l'impaginazione.TOOLget_letter_statusNumero di pagine, prezzo, anteprima, pagamento e stato della spedizione.

prepare_letter

TOOLprepare_letter

Riceve un riferimento al file dall'host, come un allegato in ChatGPT, scarica l'originale e avvia la lettera. Il file non viene mai ribattuto, ricostruito o inviato come testo. Ogni chiamata crea una nuova lettera, quindi un assistente la chiama una sola volta.

Argomenti

fileobject · obbligatorio: Il riferimento dell'host all'allegato originale dell'utente: download_url e file_id, con file_name e mime_type se noti.
fileNamestring · facoltativo: Il nome del file con la sua estensione, ad esempio letter.pdf. Serve solo se manca file.file_name.
recipientAddress · obbligatorio: Il destinatario della lettera, come confermato dall'utente. In Australia, a meno che service non sia international.
senderAddress · obbligatorio: L'indirizzo del mittente dell'utente, stampato sulla busta. Può essere in qualsiasi paese.
servicestring · facoltativo: express (predefinito), non piegata in una busta B4; regular, piegata in una busta DL, fino a 12 pagine; oppure international, con firma alla consegna.
signatureboolean · facoltativo: Firma alla consegna, $6 in più in Australia. Con la firma, la posta ordinaria viaggia come posta raccomandata.
duplexboolean · facoltativo: Stampa fronte-retro. Le dichiarazioni giurate sono sempre stampate solo fronte.
monoboolean · facoltativo: Stampa in bianco e nero. Per impostazione predefinita il colore resta a colori, senza costi aggiuntivi.
stapleboolean · facoltativo: Pinzatura delle pagine, una volta nell'angolo in alto a sinistra. Solo per documenti fino a 12 pagine; uno più lungo viene rifiutato al calcolo del prezzo. Il valore predefinito è false.
foldboolean · facoltativo: Piegare una lettera Express Post o internazionale fino a 12 pagine in una busta più piccola.
preparedForstring · facoltativo: Solo se si scrive per conto di un'azienda a uno dei suoi clienti: il nome dell'azienda, fino a 60 caratteri. La pagina di pagamento lo mostra come dichiarato dall'assistente, non come verificato, e nomi come Unopost, Australia Post, una banca o un ente pubblico vengono rifiutati.
notifyEmailstring · facoltativo: Con preparedFor: l'email dell'azienda. Riceve una copia di ogni email sulla lettera, dal pagamento alla consegna, e il cliente vede questo indirizzo prima di pagare.
customerEmailstring · facoltativo: L'email del cliente che paga, se disponibile. La pagina di pagamento la mostra già compilata; le email di tracciamento vengono inviate a questo indirizzo.

Indirizzo

name, line1 e suburb sono obbligatori; nomi e righe accettano fino a 40 caratteri. In Australia lo stato è determinato dal codice postale. Per l'estero, aggiungere country e, per una lettera verso la Cina, un numero di cellulare cinese in phone.

namestring · obbligatorio: Nome e cognome della persona.
companystring · facoltativo: Un'azienda o un'organizzazione.
line1string · obbligatorio: L'indirizzo civico, oppure una casella postale come "PO Box 123".
line2string · facoltativo: Una seconda riga dell'indirizzo.
suburbstring · obbligatorio: Il sobborgo o la località.
statestring · facoltativo: In Australia va omesso: lo determina il codice postale. Se indicato, uno tra ACT, NSW, NT, QLD, SA, TAS, VIC o WA, corrispondente al codice postale. All'estero, la regione, se il paese la usa.
postcodestring · facoltativo: Quattro cifre, obbligatorio in Australia. All'estero, il codice postale, se il paese lo usa.
countrystring · facoltativo: Va omesso per l'Australia. Altrimenti il nome del paese in inglese. Il destinatario può essere all'estero solo con service impostato su international.
phonestring · facoltativo: Solo per un destinatario in Cina: il suo numero di cellulare cinese, richiesto da China Post.

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "prepare_letter",
    "arguments": {
      "file": {
        "download_url": "https://files.example.com/letter.pdf",
        "file_id": "file_abc123",
        "file_name": "letter.pdf",
        "mime_type": "application/pdf"
      },
      "recipient": {
        "name": "Jane Citizen",
        "line1": "12 Example Street",
        "suburb": "Southbank",
        "postcode": "3006"
      },
      "sender": {
        "name": "Sam Sender",
        "line1": "1 Sample Road",
        "suburb": "Carlton",
        "postcode": "3053"
      },
      "service": "express"
    }
  }
}

structuredContent

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "reviewUrl": "https://unopost.com.au/pay?job=019d7a7f-a183-752d-9b3b-11511179033b",
  "currency": "AUD",
  "status": "CONVERTING",
  "service": "express",
  "instructions": "The letter is being laid out, usually for a few seconds. Then give the user reviewUrl to check the preview, enter an email and pay. Nothing is posted until payment. …"
}

Caricare il file direttamente

TOOLcreate_letter_upload → finish_letter_upload

Per i client che possono leggere il file dell'utente ed effettuare una richiesta HTTP, ma il cui host non ha riferimenti ai file. create_letter_upload riceve il nome del file e restituisce uploadUrl, che scade dopo 5 minuti. Inviare con PUT i byte originali a quell'indirizzo, poi chiamare finish_letter_upload con il jobId e gli stessi campi della lettera di prepare_letter.

PUT uploadUrl

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @letter.pdf

get_letter_status

TOOLget_letter_status

Indica a che punto è una lettera, con pageCount e costCents definitivi una volta impaginata. Di solito una lettera richiede pochi secondi. Interrogare al massimo ogni 5 secondi.

CONVERTED

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "reviewUrl": "https://unopost.com.au/pay?job=019d7a7f-a183-752d-9b3b-11511179033b",
  "currency": "AUD",
  "status": "CONVERTED",
  "pageCount": 3,
  "costCents": 2000,
  "previewUrl": "https://unopost.com.au/preview/019d7a7f-a183-752d-9b3b-11511179033b/letter.pdf?Expires=...&Signature=...",
  "service": "express",
  "instructions": "Ready: give the user reviewUrl to check the preview, enter an email and pay by card. The letter is posted only once it's paid for. pageCount and costCents (AUD cents) are final."
}

FAILED

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "reviewUrl": "https://unopost.com.au/pay?job=019d7a7f-a183-752d-9b3b-11511179033b",
  "currency": "AUD",
  "status": "FAILED",
  "error": "document has more than 80 pages",
  "instructions": "Not posted, and nothing was charged. The document has more than 80 pages. Suggest splitting it into separate letters of up to 80 pages each. …"
}

get_letter_info

TOOLget_letter_info

Prezzi attuali in centesimi di AUD, le pagine coperte da ciascun prezzo, i limiti di pagine e file, e risposte semplici su orari di spedizione, consegna, tracciamento e annullamento. Gli assistenti lo usano per rispondere alle domande prima di preparare qualsiasi cosa.

tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_letter_info",
    "arguments": {}
  }
}

Limiti

pages: Fino a 80 pagine per lettera. Dividere un documento più lungo in lettere separate.
regular: La posta ordinaria, e qualsiasi lettera piegata, accetta fino a 12 pagine. Le lettere più lunghe viaggiano con Express Post, non piegate.
size: Fino a 50 MB per file.
files: PDF, Word (.doc, .docx), JPEG o PNG. I documenti Word vengono impaginati in A4.
letter: Un file per lettera tramite il connettore. Il sito ne accetta fino a 10.
rate: 200 lettere l'ora da ciascun host IA.

Stati

CREATED: Riservata, in attesa del file.
CONVERTING: In impaginazione.
CONVERTED AWAITING_PAYMENT: Pronta perché l'utente la controlli e la paghi su reviewUrl.
PAID PAYING SENDING RETRYING MANUAL_CHECK: Pagata. Le lettere pagate entro le 14:30 (ora di Melbourne) di un giorno lavorativo sono spedite il giorno stesso.
POSTED UNDELIVERED: Affidata ad Australia Post. Il numero di tracciamento è stato inviato all'utente via email.
DELIVERED: Il tracciamento di Australia Post la indica come consegnata.
FAILED: Non spedita. error indica il motivo e instructions cosa fare dopo. Una lettera pagata viene rimborsata per intero.
PAYMENT_EXPIRED: Non pagata in tempo. Il documento è stato eliminato.
REFUNDED: Annullata o impossibile da spedire, e rimborsata sulla carta.

Errori

Uno strumento che non riesce restituisce un risultato di errore il cui testo, scritto per l'assistente, indica cosa è andato storto e cosa fare. Non ci sono codici di errore e i messaggi possono essere riformulati, quindi conviene agire in base al tipo di errore, non alle parole esatte.

Uno strumento non addebita né spedisce mai, quindi un errore non costa mai nulla all'utente. Ma quando un errore nomina un lavoro, quella lettera esiste: va controllata con get_letter_status invece di prepararne una seconda.

arguments: Un argomento manca o è errato: un indirizzo che l'utente dovrebbe confermare, opzioni incompatibili, un tipo di file non supportato, un preparedFor rifiutato o un'email non valida. Il messaggio lo indica. Correggerlo e chiamare di nuovo; non è stato creato nulla.
file: Non è stato possibile recuperare il file originale dall'host: il link è scaduto, è stato rifiutato, era troppo lento o ha reindirizzato troppe volte, punta a un indirizzo privato, oppure il file è vuoto o supera i 50 MB. Non è stato spedito nulla. Ottenere un nuovo riferimento al file, oppure usare create_letter_upload; non inviare mai una copia in testo al suo posto.
job …: Il messaggio inizia con job …: quando la lettera è stata creata ma un passaggio successivo non è riuscito. Chiamare get_letter_status con quell'ID del lavoro, poi finish_letter_upload se è ancora in attesa degli indirizzi. Non preparare un'altra lettera.
rate limit: Troppe lettere da questo host IA in quest'ora, oppure è stato raggiunto il limite giornaliero del connettore. Non riprovare in un ciclo: invitare l'utente a riprovare più tardi o a spedirla dal sito di Unopost.
paused: Abbiamo sospeso per un po' le nuove lettere; quelle già in lavorazione proseguono. Riprovare più tardi.
not found: Nessuna lettera ha quel jobId, oppure il suo caricamento è scaduto dopo 24 ore. Usare solo un ID del lavoro che Unopost ha restituito a questo utente, e ricominciare se è scaduto.
server: Qualcosa è andato storto da parte nostra: Unopost API returned HTTP 5xx. Attendere qualche secondo e riprovare una volta.
FAILED: Una lettera che non si può stampare non è un errore dello strumento: get_letter_status restituisce FAILED con error e instructions chiare, come dividere un documento di oltre 80 pagine o rimuovere una password.

Pagamento e privacy

Non paga né spedisce mai. Il connettore non restituisce alcun link di pagamento. L'utente paga solo sul sito, dopo aver visto l'anteprima.
Il file originale, invariato. I file non viaggiano mai all'interno dei messaggi MCP e non vengono mai sostituiti da testo.
Link privati. Un ID del lavoro è l'unica chiave di una lettera, quindi gli assistenti lo condividono, insieme a reviewUrl, solo con l'utente.
Annullamento prima della stampa. Una lettera pagata può essere annullata con rimborso completo da reviewUrl finché non iniziamo a stamparla.
Eliminati dopo la spedizione. I documenti vengono eliminati una volta spedita la lettera, e quelli di una lettera non pagata dopo 24 ore.

Webhook? Usare una casella di posta

Il connettore non ha webhook. Al loro posto, fornire all'assistente un notifyEmail di una casella di posta letta dal proprio software. Ogni email su una lettera arriva da notifications@unopost.com.au e riporta la lettera nelle intestazioni, quindi un servizio di posta che esegue codice sulla posta in arrivo, come Amazon SES, Postmark, Mailgun o SendGrid, può agire su ogni aggiornamento appena arriva.

Impostare notifyEmail su un indirizzo ricevuto dal proprio servizio di posta, ad esempio letters@yourbusiness.com.au.
Accettare solo la posta da notifications@unopost.com.au che supera il controllo DMARC e scartare il resto.
Leggere le intestazioni, non il testo, che può cambiare. Scartare un Unopost-Event-Id già visto.

Intestazioni

Unopost-Letter-Id: Il jobId della lettera, così come restituito dal connettore.
Unopost-Event: Cosa è successo: receipt, posted, tracking, retrying, delayed, awaiting-collection, delivered, cancelled, failed, refunded o refunded-printed.
Unopost-Event-Id: Resta uguale per la stessa notizia, comunque spesso venga inviata, così si possono scartare le ripetizioni.
Unopost-Letter-Status: Lo stato della lettera dopo l'evento: TO_POST, POSTED, DELAYED, AWAITING_AT_COLLECTION, DELIVERED, CANCELLED o REFUNDED.
Unopost-Tracking-Number: Il numero di tracciamento di Australia Post, una volta spedita la lettera.
Unopost-Copy: business sulla copia che riceve un'azienda; non sull'email del cliente stesso.

Headers

From: Unopost <notifications@unopost.com.au>
Unopost-Letter-Id: 019d7a7f-a183-752d-9b3b-11511179033b
Unopost-Event: tracking
Unopost-Event-Id: evt_3f9a1c0b7e2d4a6b8c1d0e2f
Unopost-Letter-Status: POSTED
Unopost-Tracking-Number: 33LQV507012301000935005
Unopost-Copy: business

Amazon SES · receipt rule Lambda

export const handler = async (event) => {
  const { mail, receipt } = event.Records[0].ses;
  const { from } = mail.commonHeaders;
  const fromUs = from.length === 1 && /(^|<)notifications@unopost\.com\.au>?$/i.test(from[0]);
  // DMARC, not DKIM alone: only a DMARC pass means unopost.com.au signed it.
  if (!fromUs || receipt.dmarcVerdict.status !== 'PASS') return;
  const header = name =>
    mail.headers.find(h => h.name.toLowerCase() === name.toLowerCase())?.value;
  await recordUpdate({
    letterId: header('Unopost-Letter-Id'),
    event: header('Unopost-Event'),
    eventId: header('Unopost-Event-Id'), // drop one you've seen
    status: header('Unopost-Letter-Status'),
    trackingNumber: header('Unopost-Tracking-Number'),
  });
};

Le copie partono quando il cliente paga, quindi per una lettera mai pagata non arriva nulla: fino ad allora controllare get_letter_status. Anche le email inviate al cliente riportano le stesse intestazioni. Potremmo aggiungere intestazioni, ma non rinomineremo né rimuoveremo mai queste.

Individuazione

Gli agenti possono trovare il connettore senza che venga loro indicato. È elencato nel nostro catalogo IA, che rimanda alla sua scheda del server MCP.

Catalogo IA /.well-known/ai-catalog.json
Scheda del server MCP /.well-known/mcp/server-card.json

Prezzi

Voce	Prezzo
Posta ordinaria, piegata per entrare nella cassetta delle lettere: fino a 12 pagine	$10
Posta raccomandata, cioè posta ordinaria con firma alla consegna: fino a 12 pagine	$16
Express Post, non piegata in busta B4: 20 pagine incluse, poi $0.30 per ogni pagina in più	$20
Express Post con firma alla consegna: 20 pagine incluse, poi $0.30 per ogni pagina in più	$26
Tracciamento, stampa a colori, fronte-retro o in bianco e nero, e pinzatura	Gratis

Ogni lettera è tracciata. Il prezzo finale dipende dal numero di pagine, noto una volta impaginata la lettera.

Le lettere preparate tramite il connettore sono disciplinate, come tutte le altre, dalle nostre Condizioni di servizio e dalla nostra Informativa sulla privacy.