curl -X POST 'https://backend.blooio.com/v1/api/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: checkout-1234' \
  -d '{ "to": "+15551234567", "text": "Thanks!" }'

​
Why idempotency

Network retries or client restarts can cause duplicate message requests. Use an Idempotency-Key header to ensure only one message is created.

​
How it works

  • Send a unique key per logical message attempt
  • If the same key is received again, the original message is returned with 200
  • New unique keys create a new message and return 202

​
Example

curl -X POST 'https://backend.blooio.com/v1/api/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: checkout-1234' \
  -d '{ "to": "+15551234567", "text": "Thanks!" }'

​
Best practices

  • Use a collision-resistant identifier (UUID v4)
  • Scope keys to your business action (e.g., order id)
  • Expire keys on the client side to avoid unbounded storage

​
Node.js example

import { randomUUID } from 'node:crypto'
import fetch from 'node-fetch'

const idempotencyKey = `order-${randomUUID()}`

const res = await fetch('https://backend.blooio.com/v1/api/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey
  },
  body: JSON.stringify({ to: '+15551234567', text: 'Order confirmed' })
})
const data = await res.json()

​
Python example

import os, uuid, requests

res = requests.post('https://backend.blooio.com/v1/api/messages',
  headers={
    'Authorization': f"Bearer {os.environ['BLOOIO_API_KEY']}",
    'Content-Type': 'application/json',
    'Idempotency-Key': f"order-{uuid.uuid4()}"
  },
  json={ 'to': '+15551234567', 'text': 'Order confirmed' }
)
data = res.json()