API reference

REST API at https://api.piisend.com. Copy-paste examples use the real endpoint https://api.piisend.com/api/v1/emails (curl, JavaScript, Python).

Call the Piisend REST API directly—each example has tabs for cURL, JavaScript (fetch), and Python (httpx). There is no installable SDK package. Delivery routing is handled on the server; your app only needs HTTPS and an API key.

Prerequisites

Create an API key with the emails:send scope (and templates:write if you create templates via API). Keys are created from the dashboard under API → Keys.

Authentication

REST API at https://api.piisend.com. Examples call https://api.piisend.com/api/v1/emails with Authorization: Bearer <YOUR_API_KEY> (pii_… prefix) and Content-Type: application/json.

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Send email — raw HTML or text

Omit template_id; provide subject plus at least one of html or text. Works for transactional and marketing messages.

curl -sS -X POST "https://api.piisend.com/api/v1/emails" \
  -H "Authorization: Bearer $PIISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["alice@example.com"],
    "subject": "Welcome to Example",
    "html": "<h1>Hi Alice</h1><p>Thanks for signing up.</p>",
    "text": "Hi Alice, thanks for signing up."
  }'

Send email — template

Use a dashboard template and pass template_vars. Do not send subject, html, or text in the same request as template_id.

curl -sS -X POST "https://api.piisend.com/api/v1/emails" \
  -H "Authorization: Bearer $PIISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["alice@example.com"],
    "template_id": "YOUR_TEMPLATE_ID",
    "template_vars": {
      "firstName": "Alice",
      "signupUrl": "https://app.example.com/welcome"
    }
  }'

OTP email (with idempotency)

Pass Idempotency-Key so retries after network errors do not double-send the same OTP.

curl -sS -X POST "https://api.piisend.com/api/v1/emails" \
  -H "Authorization: Bearer $PIISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp:user@example.com:842913" \
  -d '{
    "to": ["user@example.com"],
    "template_id": "YOUR_OTP_TEMPLATE_ID",
    "template_vars": {
      "name": "Rao",
      "otp_code": "842913",
      "expires_in": "10 minutes"
    }
  }'

Create template

POST /templates creates a reusable template; use its id when sending.

curl -sS -X POST "https://api.piisend.com/api/v1/templates" \
  -H "Authorization: Bearer $PIISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "otp-login",
    "subject": "Your OTP code is {{otp_code}}",
    "html_body": "<h1>Hi {{name}}</h1><p>Your OTP is <b>{{otp_code}}</b></p>",
    "text_body": "Hi {{name}}, your OTP is {{otp_code}}."
  }'

Errors

Non-2xx responses return JSON with a detail field when available.

# HTTP 4xx/5xx — body is JSON, e.g. {"detail":"..."}
curl -i -X POST "https://api.piisend.com/api/v1/emails" ...

Domain behavior

If you omit from_ (or have no verified domain yet), Piisend sends from the shared platform domain (see your dashboard for the exact address). After DNS verification, set from_ to your verified sender and optionally domain_id when sending.

Useful endpoints

POST /emails — send transactional, marketing, or templated mail
GET /emails — list sent or scheduled mail
POST /templates — create reusable templates
GET /templates — list templates for your workspace