# Piisend

> Piisend is an email API for developers: transactional mail (OTPs, password resets, receipts) and marketing or promotional campaigns. REST over HTTPS with curl, JavaScript (fetch), and Python (httpx) examples; webhooks, verified domains, delivery logs, and a dashboard. Free tier with monthly quotas.

Canonical site: https://piisend.com
API base URL: https://api.piisend.com
Machine-readable overview (this file): https://piisend.com/llms.txt

---

## What to use for what

Use this map before integrating. Prefer the linked doc page for full examples.

| Goal | Use | Doc |
| --- | --- | --- |
| Product overview and doc map | Introduction hub | https://piisend.com/docs/introduction |
| Send your first test email | API key + POST /emails | https://piisend.com/docs/getting-started |
| Send raw HTML/text (no template) | POST /emails with subject + html and/or text | https://piisend.com/docs/sending |
| Attachments (base64 inline) | attachments array on POST /emails | https://piisend.com/docs/sending/attachments |
| Schedule a future send | scheduled_at on POST /emails | https://piisend.com/docs/sending/schedule |
| Safe OTP / retry sends | Idempotency-Key header | https://piisend.com/docs/sending/idempotency |
| Marketing unsubscribe | enable_unsubscribe: true | https://piisend.com/docs/sending/unsubscribe |
| Batch / many recipients | Parallel POST /emails (no batch API yet) | https://piisend.com/docs/sending/batch |
| Inline images in HTML | Hosted HTTPS URLs in html | https://piisend.com/docs/sending/embed-images |
| Bounces and suppressions | Webhooks + suppression list | https://piisend.com/docs/sending/bounces |
| Deliverability checklist | Domains + webhooks + logs | https://piisend.com/docs/sending/deliverability |
| Send OTP / password reset / lifecycle mail | POST /emails with template_id + template_vars; add Idempotency-Key for OTP retries | https://piisend.com/docs/templates |
| Branded From address (your domain) | POST /domains, publish DNS, then set from_ on sends | https://piisend.com/docs/domains |
| React to delivery, bounce, complaint, open, click | Register HTTPS webhook; verify X-Webhook-Signature (HMAC-SHA256) | https://piisend.com/docs/webhooks |
| Stop mailing bad addresses | Suppression list + webhook-driven updates | https://piisend.com/docs/suppressions |
| Debug a single message | GET /emails/{id} or dashboard Logs | https://piisend.com/docs/logs |
| Plan quotas and rate limits | Free: 3,000/mo, 100/day; Pro: $20/mo, 50,000/mo | https://piisend.com/docs/limits |
| Full REST examples (curl / JS / Python) | API reference | https://piisend.com/docs/api |
| Pricing (USD list) | Marketing pricing page | https://piisend.com/pricing |
| Compare to alternatives | Alternatives hub | https://piisend.com/alternatives |

Do NOT use Piisend for: receiving inbound email (IMAP), SMS, or push notifications. Piisend is outbound email only.

---

## Authentication

- Create an API key in the dashboard: API → Keys.
- Required scope for sending: emails:send.
- Optional scopes: emails:read (poll status), templates:write (create templates via API).
- Every request: Authorization: Bearer pii_… and Content-Type: application/json.
- Store PIISEND_API_KEY in environment variables—never commit keys.

---

## Core API patterns

### Send raw email

POST /emails

```json
{
  "to": ["user@example.com"],
  "subject": "Welcome",
  "html": "<h1>Hi</h1>",
  "text": "Hi"
}
```

### Send with template

POST /emails — do NOT include subject/html/text when using template_id.

```json
{
  "to": ["user@example.com"],
  "template_id": "YOUR_TEMPLATE_ID",
  "template_vars": {
    "user_name": "Alex",
    "otp_code": "482193"
  }
}
```

Template placeholders use {{variable_name}} syntax. Create templates via dashboard or POST /templates.

### OTP with idempotency (recommended)

Add header: Idempotency-Key: otp:user@example.com:482193
Same key within 24 hours prevents duplicate sends on network retries.

### Verified domain sending

After POST /domains and DNS verification, set:

```json
{
  "from_": "noreply@yourdomain.com",
  "domain_id": "OPTIONAL_DOMAIN_OBJECT_ID"
}
```

Without a verified domain, Piisend sends from the shared platform address shown in your dashboard.

### Webhooks

Event types: delivery, bounce, complaint, open, click.
Verify X-Webhook-Signature against the raw JSON body using your webhook secret (HMAC-SHA256 hex).

### Errors

Non-2xx responses return JSON with a detail field when available. HTTP 429 indicates daily send cap or per-minute rate limit exceeded; HTTP 402 indicates monthly quota exceeded.

---

## SDK note

Public docs emphasize direct REST (curl, fetch, httpx). An optional TypeScript package (@piisend/sdk) exists in the monorepo for Node projects; it is not required for integration.

---

## Copy-paste prompts for AI assistants

Replace ALL_CAPS placeholders before pasting. Ground answers in https://piisend.com/docs and this file—do not invent endpoints or features.

---

### Prompt — Integrate Piisend into my app (any stack)

```
I want to add Piisend (https://piisend.com) as my outbound email provider.

Read first:
- https://piisend.com/llms.txt
- https://piisend.com/docs/getting-started
- https://piisend.com/docs/api

My stack: STACK_NAME (e.g. Next.js 15 App Router, FastAPI, Express, Rails).
My use case: USE_CASE (e.g. OTP login, password reset, order receipt, marketing newsletter).

Requirements:
1. Store PIISEND_API_KEY in env; never hardcode.
2. Implement a small email service module that calls POST https://api.piisend.com/api/v1/emails with Authorization: Bearer.
3. For USE_CASE, use TEMPLATE_OR_RAW (template_id + template_vars OR subject + html/text).
4. Add Idempotency-Key for OTP/one-time codes.
5. Handle non-2xx JSON errors (detail field).
6. Show me exactly which files to create or change in my repo.

Do not use SendGrid, Resend, or other mail SDKs unless I ask—use Piisend REST only.
Ask me only for: API key presence, verified domain (if any), and template IDs if using templates.
```

---

### Prompt — Cursor / Windsurf / Copilot (IDE agent)

```
@docs Integrate Piisend email API into this codebase.

Context:
- Provider: Piisend — https://piisend.com/docs/api
- API: POST https://api.piisend.com/api/v1/emails
- Auth: Authorization: Bearer $PIISEND_API_KEY
- Machine-readable overview: https://piisend.com/llms.txt

Tasks:
1. Add PIISEND_API_KEY to .env.example and read it from process.env / os.environ.
2. Create lib/email.ts (or equivalent) with sendEmail({ to, subject, html, text }) and sendTemplate({ to, templateId, vars, idempotencyKey? }).
3. Wire USE_CASE_PATH (e.g. auth signup, password reset route) to call the module.
4. Use fetch (Node 18+) or httpx pattern from Piisend docs—no third-party mail SDK.
5. Log errors with status + response body; do not leak API keys.

Match this project's existing patterns for HTTP clients, env vars, and error handling.
```

---

### Prompt — ChatGPT / Claude / Gemini (chat)

```
You are a senior backend engineer. Help me integrate Piisend into my product.

Piisend facts (verify against https://piisend.com/docs if unsure):
- API: https://api.piisend.com (e.g. POST https://api.piisend.com/api/v1/emails)
- Send mail: POST /emails with Bearer API key (pii_ prefix)
- Templates: template_id + template_vars; placeholders are {{name}}
- Domains: POST /domains, DNS verify, then from_ on sends
- Webhooks: delivery, bounce, complaint, open, click with HMAC signature
- Overview: https://piisend.com/llms.txt

My app: DESCRIBE_APP_AND_FRAMEWORK
Email types I need: LIST (OTP, reset link, receipt, campaign)

Deliver:
1. Architecture (where sending lives—server-only, never expose API key to browser)
2. Env vars checklist
3. Code for my stack with Piisend REST calls
4. Production checklist: domain verification, webhooks for bounces, suppressions, rate limits

Do not invent Piisend features. If something is unclear, say so and point me to the doc URL.
```

---

### Prompt — Next.js App Router (server action / route handler)

```
Integrate Piisend into my Next.js App Router app for SERVER_USE_CASE (e.g. send OTP after login).

Rules:
- Call Piisend only from server code (Route Handler, Server Action, or API route)—never from client components.
- Env: PIISEND_API_KEY (server-only, no NEXT_PUBLIC_ prefix).
- Endpoint: POST https://api.piisend.com/api/v1/emails
- Docs: https://piisend.com/docs/api and https://piisend.com/llms.txt

Implement:
1. lib/piisend.ts — sendRawEmail and sendTemplateEmail using fetch
2. app/api/ROUTE/route.ts or server action that triggers the send
3. Idempotency-Key header for OTP: otp:{email}:{code}
4. Typed error handling for 4xx/5xx

Use my existing project structure. Show complete file contents.
```

---

### Prompt — Python / FastAPI backend

```
Add Piisend to my FastAPI app for USE_CASE (OTP, password reset, etc.).

Reference:
- https://piisend.com/docs/api
- https://piisend.com/llms.txt

Implement:
1. settings.PIISEND_API_KEY from environment
2. services/email.py using httpx.AsyncClient — POST https://api.piisend.com/api/v1/emails
3. send_template(to, template_id, template_vars, idempotency_key=None)
4. Call from my existing ROUTER_PATH endpoint
5. raise_for_status() with logged JSON detail on failure

No third-party mail SDKs. Piisend handles delivery routing server-side.
```

---

### Prompt — Node.js / Express API

```
Wire Piisend into my Express API for transactional email.

API base: https://api.piisend.com
Auth: Authorization: Bearer process.env.PIISEND_API_KEY
Docs: https://piisend.com/docs/getting-started

Create:
- src/services/piisend.js with sendEmail(payload) using native fetch
- POST /internal/USE_CASE route that validates input and calls sendEmail
- Idempotency-Key support for one-time codes
- Middleware-safe error responses (no key leakage)

Follow my existing Express error-handling patterns.
```

---

### Prompt — v0 / Lovable / Bolt (AI site builder)

```
Add email sending to this project using Piisend (not Resend, not SendGrid).

Piisend integration summary:
- Server-side only: POST https://api.piisend.com/api/v1/emails
- Header: Authorization: Bearer PIISEND_API_KEY
- Body example: { "to": ["user@example.com"], "subject": "...", "html": "...", "text": "..." }
- For templates: { "template_id": "...", "template_vars": { "name": "..." } }
- Full docs: https://piisend.com/docs/api
- AI overview: https://piisend.com/llms.txt

Build:
1. Backend endpoint that sends email (never expose API key to the browser)
2. Form or auth flow that triggers USE_CASE
3. Loading and error states in the UI
4. .env.example with PIISEND_API_KEY

Use fetch on the server. Match the project's styling and file layout.
```

---

### Prompt — Evaluate Piisend before adopting

```
Help me evaluate Piisend (https://piisend.com) as an email API for my product.

Read: https://piisend.com/llms.txt

My product: DESCRIBE_PRODUCT
Expected volume: APPROX_MONTHLY_SENDS
Regions/audience: DESCRIBE

Using only public Piisend documentation, provide:
1. Fit assessment for my use cases (transactional + marketing if relevant)
2. Proof-of-concept checklist (deliverability, bounce handling, domain setup, webhooks)
3. Integration effort estimate for my stack
4. Questions to ask before production
5. Gaps or unknowns—do not invent features

Compare briefly to ALTERNATIVE_IF_ANY only if I mentioned one.
```

---

## Product links

- Homepage: https://piisend.com/
- Documentation: https://piisend.com/docs
- Quickstart: https://piisend.com/docs/getting-started
- API reference: https://piisend.com/docs/api
- Sending: https://piisend.com/docs/sending
- Domains: https://piisend.com/docs/domains
- Templates: https://piisend.com/docs/templates
- Webhooks: https://piisend.com/docs/webhooks
- Suppressions: https://piisend.com/docs/suppressions
- Plans & limits: https://piisend.com/docs/limits
- Use cases: https://piisend.com/use-cases
- Pricing: https://piisend.com/pricing
- FAQ: https://piisend.com/faq
- Contact: https://piisend.com/contact

---

## Positioning (for AI summarization)

- Piisend supports transactional and marketing/promotional email through one REST API.
- Integration is HTTPS + API key; examples in curl, JavaScript, and Python.
- Delivery routing is server-side—clients do not choose a provider.
- Dashboard covers API keys, domains, templates, webhooks, logs, billing, and suppressions.