Registered Mail API Reference
Base URL: https://api.ttpost.com/v1/registered-mail
Authentication
All requests must include your API key in the Authorization header as a Bearer token. Use your sandbox key for testing and your production key for live sends.
curl https://api.ttpost.com/v1/registered-mail/... \ -H "Authorization: Bearer sk_test_regmail_..."
Rate limits:
- Pro tier: 100 requests / minute
- Enterprise tier: 1,000 requests / minute
Exceeded limits return 429 Too Many Requests. Retry after the delay indicated in the Retry-After header.
Send document
/v1/registered-mail
Submit a document for registered mail delivery. TTPOST matches the recipient_id against our KYC registry and queues the document for next-day or 2-day delivery.
Request body
| Parameter | Type | Description |
|---|---|---|
recipient_id | string | TTPOST KYC registry ID of the recipient |
document_url | string | HTTPS URL of the PDF to deliver (max 10 MB) |
service_tier | string | next-day or 2-day |
callback_url | string | Your webhook endpoint for delivery events |
metadata | object | Optional. Up to 10 arbitrary key-value pairs |
Example request
curl -X POST https://api.ttpost.com/v1/registered-mail \
-H "Authorization: Bearer sk_test_regmail_..." \
-H "Content-Type: application/json" \
-d '{
"recipient_id": "rt-kyc-9821",
"document_url": "https://your-cdn.com/doc.pdf",
"service_tier": "next-day",
"callback_url": "https://your-app.com/webhooks/ttpost-rm",
"metadata": { "internal_ref": "LOAN-4429-8821" }
}'
Response
{
"tracking_id": "TTRM-2026-041-X",
"status": "queued",
"estimated_delivery": "2026-08-29"
}
Retrieve status
/v1/registered-mail/{tracking_id}
Retrieve the current delivery status and event history for a document.
curl https://api.ttpost.com/v1/registered-mail/TTRM-2026-041-X \ -H "Authorization: Bearer sk_test_regmail_..."
Response
{
"tracking_id": "TTRM-2026-041-X",
"status": "delivered_signed",
"updated_at": "2026-08-27T14:23:18-04:00",
"events": [
{ "event": "queued", "at": "2026-08-27T09:00:00-04:00" },
{ "event": "in_transit", "at": "2026-08-27T11:32:00-04:00" },
{ "event": "delivered_signed", "at": "2026-08-27T14:23:18-04:00" }
]
}
Status values: queued · in_transit · delivered_signed · returned
Retrieve POD
/v1/registered-mail/{tracking_id}/pod
Retrieve the cryptographically sealed Proof of Delivery (POD) once a document has been delivered. Returns a signed PDF URL and SHA-256 seal.
curl https://api.ttpost.com/v1/registered-mail/TTRM-2026-041-X/pod \ -H "Authorization: Bearer sk_test_regmail_..."
Response
{
"pod_pdf_url": "https://pod.ttpost.com/TTRM-2026-041-X.pdf",
"crypto_seal": "sha256:a4f2e9b8c1d03e7fa8b2c74e1d9f3a2b...",
"recipient_name": "Anaya Mohammed",
"delivered_at": "2026-08-27T14:23:18-04:00",
"signature_captured": true
}
The pod_pdf_url is a signed URL valid for 24 hours. The crypto_seal value is admissible as evidence under the T&T Evidence Act 1990.
Webhooks
Subscribe by providing a callback_url when sending a document. TTPOST POSTs delivery events to this URL. Verify the X-TTPOST-Signature header (HMAC-SHA256 over the raw body with your webhook secret).
Events: delivered_signed · returned_unclaimed · sealed
Retry policy: 3 attempts with exponential backoff (1 s, 10 s, 100 s).
Sample webhook payload
{
"event": "delivered_signed",
"tracking_id": "TTRM-2026-041-X",
"timestamp": "2026-08-27T14:23:18-04:00",
"pod_pdf_url": "https://pod.ttpost.com/TTRM-2026-041-X.pdf",
"crypto_seal": "sha256:a4f2e9b8c1d03e7fa8b2c74e1d9f3a2b...",
"signature": "sha256=..."
}
Error codes
| Code | Meaning |
|---|---|
400 | Malformed request body |
401 | Invalid or missing API key |
404 | Tracking ID not found |
422 | Missing required parameter or recipient_id not in KYC registry |
429 | Rate limit exceeded — see Retry-After header |
500 | Internal server error — retry with backoff |
{
"error": "recipient_not_found",
"message": "No KYC record matches recipient_id 'rt-kyc-9999'.",
"docs": "https://developer.ttpost.com/registered-mail/errors"
}