Send content

Delivering content is the core of the Sender API: one POST puts an item in a recipient's inbox. The request is a stable envelope (the same for every content type) plus an optional attributes object whose shape depends on the content_type. This guide covers all of it.

Everything here needs the content.write scope.

The call

curl https://api.keepable.co/sender/tenants/ten_01HXP/contents \
  -H "Authorization: Bearer $KEEPABLE_TOKEN" \
  -H "Keepable-Version: 2026-05-24" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "identifier_type": "nin", "identifier": "12345678901" },
    "subject": "Your March payslip",
    "generated_at": "2026-03-28T09:00:00Z",
    "content_type": "payslip",
    "retention_days": 390,
    "parts": [
      { "name": "payslip.pdf", "media_type": "application/pdf", "data": "JVBERi0xLjcK..." }
    ],
    "attributes": { "pay_period": "2026-03", "net_pay": "250000.00", "currency": "NGN" }
  }'

const res = await fetch(
  "https://api.keepable.co/sender/tenants/ten_01HXP/contents",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Keepable-Version": "2026-05-24",
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient: { identifier_type: "nin", identifier: "12345678901" },
      subject: "Your March payslip",
      generated_at: new Date().toISOString(),
      content_type: "payslip",
      retention_days: 390,
      parts: [
        { name: "payslip.pdf", media_type: "application/pdf", data: pdfBase64 },
      ],
      attributes: { pay_period: "2026-03", net_pay: "250000.00", currency: "NGN" },
    }),
  },
);

const { content_id, status } = await res.json();

body, _ := json.Marshal(map[string]any{
    "recipient":      map[string]string{"identifier_type": "nin", "identifier": "12345678901"},
    "subject":        "Your March payslip",
    "generated_at":   time.Now().UTC().Format(time.RFC3339),
    "content_type":   "payslip",
    "retention_days": 390,
    "parts": []map[string]string{{
        "name":       "payslip.pdf",
        "media_type": "application/pdf",
        "data":       base64.StdEncoding.EncodeToString(pdfBytes),
    }},
    "attributes": map[string]string{"pay_period": "2026-03", "net_pay": "250000.00", "currency": "NGN"},
})

req, _ := http.NewRequest("POST",
    "https://api.keepable.co/sender/tenants/ten_01HXP/contents",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Keepable-Version", "2026-05-24")
req.Header.Set("Idempotency-Key", uuid.NewString())
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

{ "content_id": "cnt_01HXP", "status": "delivered" }

The content_id is also echoed in a keepable-content-id response header.

The envelope

These fields are identical for every content type:

Addressing the recipient

recipient names a single identifier explicitly, by kind:

{ "recipient": { "identifier_type": "nin",   "identifier": "12345678901" } }
{ "recipient": { "identifier_type": "email", "identifier": "ada@example.ng" } }
{ "recipient": { "identifier_type": "tin",   "identifier": "12345678-0001" } }

identifier_type is nin, email, or tin. There is no implicit priority and no multi-identifier object: you say exactly who you mean.

If the recipient is not registered and you did not set retention_days, the call returns 403 Forbidden (recipient is not reachable on Keepable) and nothing is stored. Either match first, or set retention_days to hold the item until they sign up.

Parts: the body

parts is a non-empty array, like an email with attachments. Each part has a name, a MIME media_type, and base64-encoded data:

"parts": [
  { "name": "assessment.pdf", "media_type": "application/pdf", "data": "JVBERi0xLjcK..." },
  { "name": "cover.txt",      "media_type": "text/plain",       "data": "RGVhciBBZGEs..." }
]

Alternative renderings

A part may carry alternatives: other renderings of the same document. The classic case is a text/html version of a PDF, so the item reflows on a small screen instead of forcing pinch-to-zoom. The part itself always stays the canonical, sealed rendering; an alternative is a layer the recipient app shows over it.

"parts": [
  {
    "name": "statement.pdf",
    "media_type": "application/pdf",
    "data": "JVBERi0xLjcK...",
    "alternatives": [
      { "media_type": "text/html", "role": "document", "data": "PGgxPlN0YXRlbWVudDwvaDE+" }
    ]
  }
]

This matters in Nigeria specifically: many recipients are on small screens and metered data, where a reflowable HTML view reads far better than a zoomed PDF. Provide an alternative when you can.

How the alternative is shown: the role field

An HTML alternative can play one of two parts, and the optional role field on the alternative decides which:

document is the only recognised value; an unrecognised or absent role is treated as a cover note. The field is presentation metadata only: it never changes the sealed bytes, the content hash, or the seal, so switching a rendering between cover note and document does not alter what was sealed.

Embedded images in an HTML body

When an HTML part references images (a letterhead, a logo), send them as top-level assets and reference each by a content-scoped cid:<id> URL. The recipient app serves them same-origin, so your images never load from a sender-controlled host. Each asset is a raster image (image/png, image/jpeg, image/gif, or image/webp):

"parts": [
  { "name": "letter.html", "media_type": "text/html", "data": "PGltZyBzcmM9ImNpZDpsb2dvIj4=" }
],
"assets": [
  { "id": "logo", "media_type": "image/png", "data": "iVBORw0KGgo..." }
]

Sender attestation (optional)

By default the document seal proves Keepable received the bytes intact. To also prove the document is exactly what you sent, attach a sender_signature: a base64 ECDSA P-256 signature over the canonical content hash, made with a key you register via POST /sender/tenants/{id}/sender-keys, plus the sender_key_id that produced it. Keepable verifies it and chains the seal over it. See Sender attestation keys for the full flow. It is only accepted for non-transformed content (a sanitised HTML body is rejected).

Attributes: structured per-type data

attributes carries the machine-readable fields the recipient app can render into a rich view: an invoice's amount and due date, a payslip's net pay, a statement's balances. Its shape is selected by content_type. See Content types in depth for each schema.

"content_type": "invoice",
"attributes": {
  "amount": "125000.00",
  "currency": "NGN",
  "due_date": "2026-06-30",
  "invoice_number": "INV-88213",
  "irn": "IRN-7F3A9C20-2026"
}

Metadata

metadata is a string-valued map for your own correlation ids and routing hints. Keepable stores it but never interprets or renders it:

"metadata": { "campaign_id": "spring-2026", "ledger_ref": "INV-88213" }

Retention: delivered vs retained

The response status is the one field you must branch on:

retention_days is an optional integer with two allowed values:

{ "retention_days": 390 }

When a retained item is finally delivered (because the recipient registered), its arrival fires content.arrived like any delivery. There is no separate "recipient registered" event; subscribe to content.arrived and the full lifecycle of a retained send is observable without polling.

Idempotency

Like every mutation, content delivery requires an Idempotency-Key: replay with the same key and the same body and the item is delivered exactly once. Persist the key alongside the content you are sending, so a retry after a crash reuses it.

Next