Quickstart

Send your first email with Deliver using a UAT API key and the codigo-otp template, then check its status.

Before you start

A UAT API key (prefix dlv_test_) for your application. Piensa IT issues it; see Authentication.
The email address you’ll send to must be on the list of authorized recipients for UAT.

UAT keys only reach authorized recipients

Any other address is recorded with status blocked and the message does not go out.

Send your first message

Call POST /v1/messages with the channel, the recipient, the template, the brand and the template’s data.

POST /v1/messages

curl -X POST https://deliver.piensait.com/api/v1/messages \
  -H "Authorization: Bearer $DELIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login:u_123:2026-09-16T14:05" \
  -d '{
    "channel": "email",
    "to": "laura@example.com",
    "template": {
      "slug": "codigo-otp",
      "design": "minimal"
    },
    "brand": "piensa-it",
    "data": {
      "codigo": "481205",
      "proposito": "iniciar sesión",
      "vigenciaMinutos": 10,
      "nombre": "Laura",
      "dispositivo": "Chrome en macOS",
      "ubicacion": "Medellín, Colombia"
    }
  }'

const response = await fetch("https://deliver.piensait.com/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DELIVER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "login:u_123:2026-09-16T14:05",
  },
  body: JSON.stringify({
    "channel": "email",
    "to": "laura@example.com",
    "template": {
      "slug": "codigo-otp",
      "design": "minimal"
    },
    "brand": "piensa-it",
    "data": {
      "codigo": "481205",
      "proposito": "iniciar sesión",
      "vigenciaMinutos": 10,
      "nombre": "Laura",
      "dispositivo": "Chrome en macOS",
      "ubicacion": "Medellín, Colombia"
    }
  }),
});

const { id, status } = await response.json(); // 202: { id: "msg_…", status: "queued" }

The API answers right away and sends in the background:

HTTP	Body	Meaning
`202`	`{ "id": "msg_…", "status": "queued" }`	Accepted; sending now.
`202`	`{ "id": "msg_…", "status": "blocked", "statusDetail": "…" }`	UAT key and a recipient that isn’t authorized.
`200`	Same message as before	A message with that `Idempotency-Key` already existed; nothing is sent again.

Check the status

GET /v1/messages/{id}

curl https://deliver.piensait.com/api/v1/messages/msg_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $DELIVER_API_KEY"

The response has the current status and its events. See Message status.

Next steps

Handle errors by their codigo.
Pick a design and your brand in Email templates.
Explore every endpoint in the API reference.