PostStack

https://poststack.dev/docs
Admin
PostStack is a type-safe email API for developers that enables sending transactional emails,...
Tokens:63,785
Snippets:682
Trust Score:6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the PostStack Go SDK

Source: https://poststack.dev/docs/send-with-go

Use the go get command to add the SDK to your project.

```bash
go get github.com/getpoststack/go-sdk
```

--------------------------------

### Install PostStack SDK and Hono

Source: https://poststack.dev/docs/send-with-hono

Install the necessary dependencies using your package manager.

```bash
bun add @poststack.dev/sdk hono
```

--------------------------------

### Install PostStack SDK and Express

Source: https://poststack.dev/docs/send-with-express

Install the necessary dependencies for the PostStack SDK and Express framework.

```bash
npm install @poststack.dev/sdk express
```

--------------------------------

### Install PostStack SDK

Source: https://poststack.dev/docs/send-with-nextjs

Install the required package using npm.

```bash
npm install @poststack.dev/sdk
```

--------------------------------

### Install PostStack SDK

Source: https://poststack.dev/docs/send-with-django

Install the required package via pip.

```bash
pip install poststack
```

--------------------------------

### Install the PostStack SDK

Source: https://poststack.dev/docs

Use your preferred package manager to add the PostStack SDK to your project.

```bash
bun add @poststack.dev/sdk
```

```bash
npm install @poststack.dev/sdk
```

```bash
pnpm add @poststack.dev/sdk
```

--------------------------------

### GET /templates

Source: https://poststack.dev/docs/templates

List all templates with pagination.

```APIDOC
## GET /templates

### Description
List all templates with pagination.

### Method
GET

### Endpoint
/templates

### Response
#### Success Response (200)
- **data** (array) - List of template objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [
    {
      "id": "tpl_abc123def456ghi789",
      "name": "Welcome Email",
      "status": "published",
      "created_at": "2026-03-23T10:00:00.000Z",
      "updated_at": "2026-03-23T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 12,
    "totalPages": 1
  }
}
```

--------------------------------

### GET /workflows

Source: https://poststack.dev/docs/workflows

List all workflows.

```APIDOC
## GET /workflows

### Description
List all workflows with their status and trigger type.

### Method
GET

### Endpoint
/workflows

### Response
#### Success Response (200)
- **data** (array) - List of workflow objects

#### Response Example
{
  "data": [
    {
      "id": "wf_abc123def456ghi789",
      "name": "Welcome Sequence",
      "trigger_type": "contact.created",
      "status": "active",
      "created_at": "2026-03-23T10:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Install PostStack SDK with Bun

Source: https://poststack.dev/docs/send-with-bun

Add the PostStack SDK to your project using the Bun package manager.

```bash
bun add @poststack.dev/sdk
```

--------------------------------

### GET /templates/presets

Source: https://poststack.dev/docs/templates

List available template presets from the gallery.

```APIDOC
## GET /templates/presets

### Description
List available template presets from the gallery. Presets are pre-built templates you can use as a starting point.

### Method
GET

### Endpoint
/templates/presets

### Response
#### Success Response (200)
- **data** (array) - List of preset objects

#### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "Welcome Email",
      "description": "A clean welcome email with logo and CTA",
      "subject": "Welcome!",
      "html": "<h1>Welcome</h1>...",
      "text": "Welcome..."
    }
  ]
}
```

--------------------------------

### GET /signup-forms

Source: https://poststack.dev/docs/signup-forms

List all signup forms with pagination support.

```APIDOC
## GET /signup-forms

### Description
List all signup forms with pagination.

### Method
GET

### Endpoint
/signup-forms

### Response
#### Success Response (200)
- **forms** (array) - List of signup forms
- **pagination** (object) - Pagination metadata
```

--------------------------------

### Initialize Client and Send Email

Source: https://poststack.dev/docs/sdk

Example showing how to instantiate the PostStack client and send an email using the emails resource.

```typescript
import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack('sk_live_...');

// Send an email
const { id } = await poststack.emails.send({
  from: 'PostStack <you@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Hello from PostStack',
  html: '<p>Welcome!</p>',
});

console.log('Email sent:', id);
```

--------------------------------

### Add a new domain

Source: https://poststack.dev/docs/domains

Create a new domain configuration. Returns the necessary DNS records for setup.

```json
{
  "name": "yourdomain.com",
  "region": "eu-west-1",
  "custom_return_path": "bounce.yourdomain.com",
  "open_tracking": true,
  "click_tracking": true,
  "tls_mode": "enforced"
}
```

--------------------------------

### Install Req dependency

Source: https://poststack.dev/docs/send-with-elixir

Add the Req library to your mix.exs file to enable HTTP requests.

```bash
# mix.exs
{:req, "~> 0.5"}
```

--------------------------------

### Get a signup form by ID

Source: https://poststack.dev/docs/signup-forms

Retrieves the full configuration and metadata for a specific signup form.

```json
{
  "id": 1,
  "public_id": "sf_abc123def456",
  "name": "Newsletter Signup",
  "segment_id": "seg_abc123def456",
  "topic_id": "top_xyz789ghi012",
  "fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true
    }
  ],
  "success_message": "Thanks for subscribing!",
  "redirect_url": "https://example.com/welcome",
  "active": true,
  "submission_count": 142,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-03-20T10:00:00.000Z"
}
```

--------------------------------

### GET /webhooks

Source: https://poststack.dev/docs/webhooks

List all webhook endpoints for your account.

```APIDOC
## GET /webhooks

### Description
List all webhook endpoints for your account.

### Method
GET

### Endpoint
/webhooks

### Response
#### Success Response (200)
- **webhooks** (array) - List of webhook configurations.
```

--------------------------------

### GET /subscription-topics

Source: https://poststack.dev/docs/subscription-topics

List all subscription topics.

```APIDOC
## GET /subscription-topics

### Description
List all subscription topics.

### Method
GET

### Endpoint
/subscription-topics

### Response
#### Success Response (200)
- **topics** (array) - List of subscription topics.
```

--------------------------------

### POST /templates

Source: https://poststack.dev/docs/templates

Create a new email template. Templates start in draft status.

```APIDOC
## POST /templates

### Description
Create a new email template. Templates start in draft status.

### Method
POST

### Endpoint
/templates

### Request Body
- **name** (string) - Required - The name of the template
- **subject** (string) - Required - The email subject line with optional {{variable}} placeholders
- **html** (string) - Required - The HTML content of the template
- **text** (string) - Required - The plain text content of the template
- **variables** (array) - Required - A list of variable names used in the template

### Request Example
{
  "name": "Welcome Email",
  "subject": "Welcome to {{company_name}}, {{first_name}}!",
  "html": "<h1>Hello {{first_name}},</h1><p>Welcome to {{company_name}}.</p>",
  "text": "Hello {{first_name}}, Welcome to {{company_name}}.",
  "variables": ["first_name", "company_name"]
}
```

--------------------------------

### Install PostStack dependencies

Source: https://poststack.dev/docs/send-with-rust

Add the required dependencies to your Cargo.toml file to enable JSON support and async operations.

```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
```

--------------------------------

### GET /domains

Source: https://poststack.dev/docs/domains

List all domains associated with your account along with their current verification status.

```APIDOC
## GET /domains

### Description
List all domains for your account with their verification status.

### Method
GET

### Endpoint
/domains

### Response
#### Success Response (200)
- **domains** (array) - List of domain objects.
```

--------------------------------

### GET /signup-forms/:id

Source: https://poststack.dev/docs/signup-forms

Retrieve a specific signup form by its ID, including field configurations.

```APIDOC
## GET /signup-forms/:id

### Description
Get a signup form by ID, including its full field configuration.

### Method
GET

### Endpoint
/signup-forms/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the signup form
```

--------------------------------

### Frontend form submission integration

Source: https://poststack.dev/docs/signup-forms

Example of how to submit form data from a client-side application using the Fetch API.

```typescript
async function submitForm(formId: string, email: string) {
  const response = await fetch(
    `https://api.poststack.dev/signup-forms/${formId}/submit`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    },
  );
  return response.json();
}
```

--------------------------------

### PHP cURL Security and Performance

Source: https://poststack.dev/docs/send-with-php

Examples of common cURL configuration pitfalls regarding SSL verification and handle reuse.

```php
CURLOPT_SSL_VERIFYPEER => false
```

```php
curl_init
```

```php
curl_setopt
```

--------------------------------

### List Received Inbound Emails Response

Source: https://poststack.dev/docs/inbound-email

Example JSON response for the GET /inbound endpoint.

```json
{
  "data": [
    {
      "id": 7,
      "domainId": 12,
      "fromAddress": "sender@external.com",
      "fromName": "Jane Sender",
      "toAddress": "support+invoice-42@yourdomain.com",
      "toAddresses": [{ "address": "support+invoice-42@yourdomain.com", "name": null }],
      "ccAddresses": [{ "address": "colleague@external.com", "name": "A Colleague" }],
      "messageId": "<abc123@external.com>",
      "subject": "Need help with my account",
      "htmlBody": "<p>Hi, I need help resetting my password...</p>",
      "textBody": "Hi, I need help resetting my password...",
      "headers": { "date": "Mon, 23 Mar 2026 10:00:00 +0000" },
      "createdAt": "2026-03-23T10:00:00.000Z",
      "mailboxHash": "invoice-42",
      "spamScore": 1.8,
      "spamVerdict": "clean",
      "strippedReply": "Thanks, that worked!"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 48,
    "totalPages": 3
  }
}
```

--------------------------------

### Initialize the PostStack client

Source: https://poststack.dev/docs/send-with-go

Import the package and instantiate the client using your live secret key.

```go
import (
    "context"

    poststack "github.com/getpoststack/go-sdk"
)

client := poststack.NewClient("sk_live_...")
```

--------------------------------

### GET /templates/:id

Source: https://poststack.dev/docs/templates

Retrieve a single template including its full HTML content and variable list.

```APIDOC
## GET /templates/:id

### Description
Retrieve a single template including its full HTML content and variable list.

### Method
GET

### Endpoint
/templates/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the template

### Response
#### Success Response (200)
- **template** (object) - The template details

#### Response Example
{
  "template": {
    "id": "tpl_abc123def456ghi789",
    "name": "Welcome Email",
    "subject": "Welcome to {{company_name}}, {{first_name}}!",
    "html": "<h1>Hello {{first_name}},</h1><p>Welcome to {{company_name}}.</p>",
    "text": "Hello {{first_name}}, Welcome to {{company_name}}.",
    "status": "published",
    "variables": ["first_name", "company_name"],
    "created_at": "2026-03-23T10:00:00.000Z",
    "updated_at": "2026-03-23T12:00:00.000Z"
  }
}
```

--------------------------------

### Initialize PostStack with Test API Key

Source: https://poststack.dev/docs/test-mode

Use an API key starting with 'sk_test_' to ensure no emails are delivered while still receiving simulated event IDs.

```typescript
import { PostStack } from '@poststack.dev/sdk';

// Use a test key -- no real emails will be sent
const poststack = new PostStack('sk_test_...');

// This email is validated and queued, but never delivered
const { id } = await poststack.emails.send({
  from: 'you@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Test Email',
  html: '<p>This is a test.</p>',
});

// id is still returned, and events are simulated
```

--------------------------------

### List Inbound Email Attachments Response

Source: https://poststack.dev/docs/inbound-email

Example JSON response for the GET /inbound/:id/attachments endpoint.

```json
{
  "attachments": [
    {
      "id": 1,
      "filename": "screenshot.png",
      "contentType": "image/png",
      "size": 24576,
      "createdAt": "2026-03-23T10:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Retrieve Single Inbound Email Response

Source: https://poststack.dev/docs/inbound-email

Example JSON response for the GET /inbound/:id endpoint.

```json
{
  "inboundEmail": {
    "id": 7,
    "domainId": 12,
    "fromAddress": "sender@external.com",
    "fromName": "Jane Sender",
    "toAddress": "support@yourdomain.com",
    "toAddresses": [{ "address": "support@yourdomain.com", "name": null }],
    "ccAddresses": [{ "address": "colleague@external.com", "name": "A Colleague" }],
    "messageId": "<abc123@external.com>",
    "subject": "Need help with my account",
    "htmlBody": "<p>Hi, I need help resetting my password...</p>",
    "textBody": "Hi, I need help resetting my password...",
    "headers": {
      "date": "Mon, 23 Mar 2026 10:00:00 +0000"
    },
    "createdAt": "2026-03-23T10:00:00.000Z",
    "mailboxHash": null,
    "spamScore": 1.8,
    "spamVerdict": "clean",
    "strippedReply": "Hi, I need help resetting my password..."
  }
}
```

--------------------------------

### Initialize PostStack and Hono

Source: https://poststack.dev/docs/send-with-hono

Set up the PostStack client and Hono application instance.

```typescript
import { PostStack } from '@poststack.dev/sdk';
import { Hono } from 'hono';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);
const app = new Hono();
```

--------------------------------

### Example Email Event Payload

Source: https://poststack.dev/docs/tracking

Shows the structure of an email event payload containing client, OS, and location data.

```json
{
  "type": "email.opened",
  "timestamp": "2026-03-23T10:01:15.000Z",
  "data": {
    "email_id": "em_abc123def456ghi789",
    "client": {
      "name": "Apple Mail",
      "type": "desktop",
      "os": "macOS"
    },
    "location": {
      "country": "US",
      "region": "California",
      "city": "San Francisco"
    }
  }
}
```

--------------------------------

### GET /emails/:id/insights

Source: https://poststack.dev/docs/emails

Get delivery insights and warnings for an email.

```APIDOC
## GET /emails/:id/insights

### Description
Get delivery insights and warnings for an email, such as missing authentication records or content issues.

### Method
GET

### Endpoint
/emails/:id/insights

### Parameters
#### Path Parameters
- **id** (string) - Required - The email ID

### Response
#### Success Response (200)
- **warnings** (array) - List of warning objects

### Response Example
{
  "warnings": [
    {
      "type": "missing_dkim",
      "message": "DKIM record not found for this domain",
      "severity": "high"
    },
    {
      "type": "large_html",
      "message": "HTML content exceeds 100KB which may cause clipping",
      "severity": "low"
    }
  ]
}
```

--------------------------------

### Initialize the PostStack client

Source: https://poststack.dev/docs/send-with-java

Sets up the standard Java HttpClient and retrieves the API key from environment variables.

```java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
String apiKey = System.getenv("POSTSTACK_API_KEY");
```

--------------------------------

### GET /broadcasts/:id/variant-stats

Source: https://poststack.dev/docs/broadcasts

Get performance statistics for A/B test variants.

```APIDOC
## GET /broadcasts/:id/variant-stats

### Description
Get performance statistics for A/B test variants, including which variant won.

### Method
GET

### Endpoint
/broadcasts/:id/variant-stats

### Parameters
#### Path Parameters
- **id** (string) - Required - The broadcast ID
```

--------------------------------

### Configure Django SMTP Backend for PostStack

Source: https://poststack.dev/docs/send-with-django

Configures Django's built-in email backend to use PostStack SMTP. Includes examples for standard email, HTML alternatives, and file attachments.

```python
# settings.py — route Django's built-in email through PostStack over SMTP
import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.poststack.dev"
EMAIL_PORT = 587
EMAIL_USE_SSL = True            # implicit TLS on 587 (RFC 8314) — do NOT also set EMAIL_USE_TLS
EMAIL_HOST_USER = "poststack"
EMAIL_HOST_PASSWORD = os.environ["POSTSTACK_API_KEY"]
DEFAULT_FROM_EMAIL = "hello@yourdomain.com"

# 1. send_mail — the one-liner
from django.core.mail import send_mail

send_mail(
    "Welcome to Acme",
    "Thanks for signing up.",
    None,                       # None uses DEFAULT_FROM_EMAIL
    ["user@example.com"],
)

# 2. EmailMultiAlternatives — HTML with a plain-text fallback
from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Welcome",
    body="Thanks for signing up.",          # text/plain part
    to=["user@example.com"],
)
msg.attach_alternative("<h1>Welcome!</h1>", "text/html")
msg.send()

# 3. EmailMessage — attach a file (e.g. a PDF receipt)
from django.core.mail import EmailMessage

email = EmailMessage(
    subject="Your receipt",
    body="Your receipt is attached.",
    to=["user@example.com"],
)
email.attach("receipt.pdf", pdf_bytes, "application/pdf")
email.send()
```

--------------------------------

### Create and activate a welcome sequence workflow

Source: https://poststack.dev/docs/workflows

Demonstrates the full lifecycle of a workflow including creation, adding sequential steps, and activation.

```typescript
// 1. Create the workflow
const { workflow } = await poststack.workflows.create({
  name: 'Welcome Sequence',
  trigger_type: 'contact.created',
});

// 2. Add steps in order
await poststack.workflows.addStep(workflow.id, {
  step_type: 'send_email',
  config: { templateId: 'tpl_welcome' },
  position: 0,
});

await poststack.workflows.addStep(workflow.id, {
  step_type: 'wait',
  config: { duration: 3, unit: 'days' },
  position: 1,
});

await poststack.workflows.addStep(workflow.id, {
  step_type: 'send_email',
  config: { templateId: 'tpl_getting_started' },
  position: 2,
});

// 3. Activate the workflow
await poststack.workflows.activate(workflow.id);
```

--------------------------------

### Initialize the PostStack client

Source: https://poststack.dev/docs/send-with-ruby

Sets up the required standard library modules and defines the API key and base URL for the PostStack service.

```ruby
require 'net/http'
require 'json'
require 'uri'

API_KEY = ENV['POSTSTACK_API_KEY']
BASE_URL = 'https://api.poststack.dev'
```

--------------------------------

### SDK Initialization

Source: https://poststack.dev/docs/authentication

How to initialize the PostStack SDK with an API key.

```APIDOC
## SDK Initialization

### Description
Initialize the PostStack client by passing your secret API key to the constructor.

### Code Example
```typescript
import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack('sk_live_...');
```
```

--------------------------------

### Initialize PostStack client

Source: https://poststack.dev/docs/send-with-python

Create an instance of the synchronous PostStack client using your API key.

```python
from poststack import PostStack

ps = PostStack(api_key="sk_live_...")
```

--------------------------------

### GET /broadcasts

Source: https://poststack.dev/docs/broadcasts

List all broadcasts with pagination.

```APIDOC
## GET /broadcasts

### Description
List all broadcasts with pagination.

### Method
GET

### Endpoint
/broadcasts

### Response
#### Success Response (200)
- **data** (array) - List of broadcast objects
- **meta** (object) - Pagination metadata
```

--------------------------------

### Initialize the PostStack client

Source: https://poststack.dev/docs/send-with-rust

Create a new reqwest client and retrieve the API key from environment variables.

```rust
use reqwest::Client;

let client = Client::new();
let api_key = std::env::var("POSTSTACK_API_KEY")?;
```

--------------------------------

### GET /workflows/:id

Source: https://poststack.dev/docs/workflows

Retrieve a single workflow.

```APIDOC
## GET /workflows/:id

### Description
Retrieve a single workflow with all steps and configuration.

### Method
GET

### Endpoint
/workflows/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The workflow ID

### Response
#### Success Response (200)
- **workflow** (object) - The workflow details including steps
```

--------------------------------

### Initialize PostStack Client

Source: https://poststack.dev/docs/send-with-django

Configure the API key in settings and initialize the client in a dedicated service module.

```python
# settings.py — read the key from the environment, never hardcode it
import os

POSTSTACK_API_KEY = os.environ["POSTSTACK_API_KEY"]

# emails.py — a thin service module your views and tasks import
from poststack import PostStack
from django.conf import settings

ps = PostStack(api_key=settings.POSTSTACK_API_KEY)
```

--------------------------------

### GET /notification-channels

Source: https://poststack.dev/docs/notification-channels

List all notification channels for the team.

```APIDOC
## GET /notification-channels

### Description
List all notification channels for your team. Secrets in config are masked.

### Method
GET

### Endpoint
/notification-channels
```

--------------------------------

### GET /mailboxes/aliases

Source: https://poststack.dev/docs/mailboxes

List all aliases for the current team.

```APIDOC
## GET /mailboxes/aliases

### Description
List all aliases for the current team.

### Method
GET

### Endpoint
/mailboxes/aliases
```

--------------------------------

### Initialize PostStack and Express

Source: https://poststack.dev/docs/send-with-express

Set up the PostStack client and Express application instance at the module scope.

```typescript
import { PostStack } from '@poststack.dev/sdk';
import express from 'express';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);
const app = express();
app.use(express.json());
```

--------------------------------

### GET /segments

Source: https://poststack.dev/docs/segments

List all segments with contact counts.

```APIDOC
## GET /segments

### Description
List all segments with contact counts.

### Method
GET

### Endpoint
/segments

### Response
#### Success Response (200)
- **segments** (array) - List of segments.
```

--------------------------------

### Create Template from Preset

Source: https://poststack.dev/docs/templates

Response after creating a new template based on a preset.

```json
HTTP/1.1 201 Created

{
  "template": {
    "id": "tpl_new_from_preset",
    "name": "Welcome Email",
    "subject": "Welcome!",
    "status": "draft",
    "created_at": "2026-03-23T16:00:00.000Z"
  }
}
```

--------------------------------

### Initialize the PostStack client

Source: https://poststack.dev/docs/send-with-php

Set up the API key and base URL variables for use in subsequent cURL requests.

```php
$apiKey = getenv('POSTSTACK_API_KEY');
$baseUrl = 'https://api.poststack.dev';
```

--------------------------------

### GET /inbound/:id/attachments/:aid

Source: https://poststack.dev/docs/inbound-email

Download a specific attachment.

```APIDOC
## GET /inbound/:id/attachments/:aid

### Description
Download a specific attachment. Returns the raw file content with the appropriate Content-Type header.

### Method
GET

### Endpoint
/inbound/:id/attachments/:aid

### Parameters
#### Path Parameters
- **id** (numeric) - Required - The ID of the inbound email
- **aid** (numeric) - Required - The ID of the attachment
```

--------------------------------

### GET /inbound/:id/attachments

Source: https://poststack.dev/docs/inbound-email

List all attachments for an inbound email.

```APIDOC
## GET /inbound/:id/attachments

### Description
List all attachments for an inbound email.

### Method
GET

### Endpoint
/inbound/:id/attachments

### Parameters
#### Path Parameters
- **id** (numeric) - Required - The ID of the inbound email

### Response
#### Success Response (200)
- **attachments** (array) - List of attachment objects
```

--------------------------------

### Initialize PostStack client in FastAPI

Source: https://poststack.dev/docs/send-with-fastapi

Create a shared AsyncPostStack client using a lifespan context manager and expose it via a dependency.

```python
# main.py — create one AsyncPostStack for the app lifespan
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from poststack import AsyncPostStack

@asynccontextmanager
async def lifespan(app: FastAPI):
    # The async client is itself an async context manager, so open it for the
    # app's lifetime and let it clean up its connection pool on shutdown.
    async with AsyncPostStack(api_key=os.environ["POSTSTACK_API_KEY"]) as ps:
        app.state.poststack = ps
        yield

app = FastAPI(lifespan=lifespan)

# dependency — inject the shared client into route handlers
from fastapi import Request

def get_poststack(request: Request) -> AsyncPostStack:
    return request.app.state.poststack
```

--------------------------------

### GET /mailboxes

Source: https://poststack.dev/docs/mailboxes

List all mailboxes for the current team with pagination.

```APIDOC
## GET /mailboxes

### Description
List all mailboxes for the current team with pagination.

### Method
GET

### Endpoint
/mailboxes
```

--------------------------------

### List Template Presets

Source: https://poststack.dev/docs/templates

Response listing available pre-built template presets.

```json
{
  "data": [
    {
      "id": 1,
      "name": "Welcome Email",
      "description": "A clean welcome email with logo and CTA",
      "subject": "Welcome!",
      "html": "<h1>Welcome</h1>...",
      "text": "Welcome..."
    },
    {
      "id": 2,
      "name": "Newsletter",
      "description": "Multi-section newsletter layout",
      "subject": "Your Weekly Update",
      "html": "<h1>Newsletter</h1>...",
      "text": "Newsletter..."
    }
  ]
}
```

--------------------------------

### GET /webhooks/:id/deliveries

Source: https://poststack.dev/docs/webhooks

List recent webhook delivery attempts.

```APIDOC
## GET /webhooks/:id/deliveries

### Description
List recent webhook delivery attempts with status, response codes, and timestamps.

### Method
GET

### Endpoint
/webhooks/:id/deliveries

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the webhook.
```

--------------------------------

### POST /templates/presets/:presetId/use

Source: https://poststack.dev/docs/templates

Create a new template from a preset.

```APIDOC
## POST /templates/presets/:presetId/use

### Description
Create a new template from a preset. The template starts in draft status with the preset's content.

### Method
POST

### Endpoint
/templates/presets/:presetId/use

### Parameters
#### Path Parameters
- **presetId** (string) - Required - The ID of the preset to use

### Response
#### Success Response (201)
- **template** (object) - The newly created template

#### Response Example
{
  "template": {
    "id": "tpl_new_from_preset",
    "name": "Welcome Email",
    "subject": "Welcome!",
    "status": "draft",
    "created_at": "2026-03-23T16:00:00.000Z"
  }
}
```

--------------------------------

### GET /webhooks/:id

Source: https://poststack.dev/docs/webhooks

Retrieve a single webhook endpoint with its configuration.

```APIDOC
## GET /webhooks/:id

### Description
Retrieve a single webhook endpoint with its configuration.

### Method
GET

### Endpoint
/webhooks/:id

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the webhook.
```

--------------------------------

### GET /emails/:id/events

Source: https://poststack.dev/docs/emails

Retrieve the full event history for an email.

```APIDOC
## GET /emails/:id/events

### Description
Retrieve the full event history for an email, including timestamps for each status change.

### Method
GET

### Endpoint
/emails/:id/events

### Parameters
#### Path Parameters
- **id** (string) - Required - The email ID

### Response
#### Success Response (200)
- **events** (array) - List of event objects

### Response Example
{
  "events": [
    { "type": "queued", "timestamp": "2026-03-23T10:00:00.000Z" },
    { "type": "sent", "timestamp": "2026-03-23T10:00:01.000Z" },
    { "type": "delivered", "timestamp": "2026-03-23T10:00:02.000Z" },
    { "type": "opened", "timestamp": "2026-03-23T10:01:15.000Z" },
    { "type": "clicked", "timestamp": "2026-03-23T10:02:30.000Z" }
  ]
}
```

--------------------------------

### Create a new workflow

Source: https://poststack.dev/docs/workflows

Initializes a workflow in 'draft' status.

```json
{
  "name": "Welcome Sequence",
  "trigger_type": "contact.created",
  "trigger_config": {}
}
```

--------------------------------

### GET /subscription-topics/contacts/:contactId/subscriptions

Source: https://poststack.dev/docs/subscription-topics

List all topic subscriptions for a specific contact.

```APIDOC
## GET /subscription-topics/contacts/:contactId/subscriptions

### Description
List all topic subscriptions for a specific contact.

### Method
GET

### Endpoint
/subscription-topics/contacts/:contactId/subscriptions

### Parameters
#### Path Parameters
- **contactId** (string) - Required - The ID of the contact.
```

--------------------------------

### Initialize PostStack Client

Source: https://poststack.dev/docs/send-with-bun

Create a new PostStack instance using your API key from environment variables.

```typescript
import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);
```

--------------------------------

### GET /suppressions

Source: https://poststack.dev/docs/suppressions

Retrieves a paginated list of all suppressed email addresses.

```APIDOC
## GET /suppressions

### Description
List all suppressed email addresses with pagination.

### Method
GET

### Endpoint
/suppressions

### Response
#### Success Response (200)
- **data** (array) - List of suppressed email objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [
    {
      "id": 1,
      "email": "bounced@example.com",
      "reason": "hard_bounce",
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 24,
    "totalPages": 2
  }
}
```

--------------------------------

### GET /contact-properties

Source: https://poststack.dev/docs/contact-properties

List all custom contact properties defined for your team.

```APIDOC
## GET /contact-properties

### Description
List all custom contact properties defined for your team.

### Method
GET

### Endpoint
/contact-properties

### Response
#### Success Response (200)
- **properties** (array) - List of contact property objects

#### Response Example
{
  "properties": [
    {
      "id": 1,
      "name": "plan",
      "label": "Subscription Plan",
      "type": "select",
      "options": ["free", "pro", "scale"],
      "required": false,
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}
```

--------------------------------

### List all signup forms

Source: https://poststack.dev/docs/signup-forms

Retrieves a paginated list of all existing signup forms.

```json
{
  "forms": [
    {
      "id": 1,
      "public_id": "sf_abc123def456",
      "name": "Newsletter Signup",
      "active": true,
      "submission_count": 142,
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}
```

--------------------------------

### GET /broadcasts/:id/variants

Source: https://poststack.dev/docs/broadcasts

List A/B test variants for a broadcast.

```APIDOC
## GET /broadcasts/:id/variants

### Description
List A/B test variants for a broadcast. Only available when the broadcast was created with A/B testing.

### Method
GET

### Endpoint
/broadcasts/:id/variants

### Parameters
#### Path Parameters
- **id** (string) - Required - The broadcast ID
```

--------------------------------

### GET /inbound/:id

Source: https://poststack.dev/docs/inbound-email

Retrieve a single inbound email with full content.

```APIDOC
## GET /inbound/:id

### Description
Retrieve a single inbound email with full content.

### Method
GET

### Endpoint
/inbound/:id

### Parameters
#### Path Parameters
- **id** (numeric) - Required - The ID of the inbound email

### Response
#### Success Response (200)
- **inboundEmail** (object) - The requested email details
```

--------------------------------

### GET /broadcasts/:id

Source: https://poststack.dev/docs/broadcasts

Retrieve a single broadcast with delivery statistics and configuration.

```APIDOC
## GET /broadcasts/:id

### Description
Retrieve a single broadcast with delivery statistics and configuration.

### Method
GET

### Endpoint
/broadcasts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The broadcast ID
```

--------------------------------

### Initialize PostStack API key

Source: https://poststack.dev/docs/send-with-elixir

Configure the API key in your application config using environment variables.

```elixir
# config/config.exs
config :my_app,
  poststack_api_key: System.get_env("POSTSTACK_API_KEY")
```

--------------------------------

### Initialize PostStack client in Flask

Source: https://poststack.dev/docs/send-with-flask

Store the PostStack client in app.extensions within the app factory to make it accessible via current_app.

```python
# app.py — initialise the client once in your app factory
import os
from flask import Flask
from poststack import PostStack

def create_app():
    app = Flask(__name__)
    # Store the client on app.extensions so views can reach it via current_app
    app.extensions["poststack"] = PostStack(api_key=os.environ["POSTSTACK_API_KEY"])
    return app
```

--------------------------------

### Retrieve a single broadcast

Source: https://poststack.dev/docs/broadcasts

Get detailed configuration and delivery statistics for a specific broadcast.

```json
{
  "broadcast": {
    "id": "bc_abc123def456ghi789",
    "name": "March Newsletter",
    "status": "sent",
    "from": "Newsletter <newsletter@yourdomain.com>",
    "subject": "What's new in March",
    "html": "<h1>March Updates</h1><p>Here's what happened...</p>",
    "segmentId": 1,
    "totalRecipients": 1250,
    "deliveredCount": 1230,
    "bouncedCount": 12,
    "openedCount": 456,
    "clickedCount": 89,
    "sentAt": "2026-03-25T09:00:00.000Z",
    "createdAt": "2026-03-23T10:00:00.000Z"
  }
}
```

--------------------------------

### GET /segments/:id

Source: https://poststack.dev/docs/segments

Retrieve a single segment with its rules (if dynamic) and contact count.

```APIDOC
## GET /segments/:id

### Description
Retrieve a single segment with its rules (if dynamic) and contact count.

### Method
GET

### Endpoint
/segments/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the segment.
```

--------------------------------

### Enable Catch-All for a Domain

Source: https://poststack.dev/docs/domains

Configures a domain to accept emails sent to any address, regardless of whether a mailbox exists.

```typescript
await poststack.domains.update('dom_abc123def456', {
  catch_all: true,
});
```

--------------------------------

### Generate Claude Desktop Configuration

Source: https://poststack.dev/docs/mcp

Command to automatically generate the required configuration snippet for Claude Desktop.

```bash
npx @poststack.dev/mcp --print-config claude-desktop
```

--------------------------------

### Initialize PostStack SDK

Source: https://poststack.dev/docs/authentication

Pass the API key during client initialization when using the TypeScript SDK.

```typescript
import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack('sk_live_...');
```

--------------------------------

### Publish Template

Source: https://poststack.dev/docs/templates

Response after successfully publishing a draft template.

```json
{
  "template": {
    "id": "tpl_abc123def456ghi789",
    "status": "published",
    "published_at": "2026-03-23T15:00:00.000Z"
  }
}
```

--------------------------------

### GET /emails/:id

Source: https://poststack.dev/docs/emails

Retrieve a single email by ID, including delivery events and metadata.

```APIDOC
## GET /emails/:id

### Description
Retrieve a single email by ID, including delivery events and metadata.

### Method
GET

### Endpoint
/emails/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The email ID

### Response
#### Success Response (200)
- **email** (object) - Email details

### Response Example
{
  "email": {
    "id": "em_abc123def456ghi789",
    "from": "PostStack <you@yourdomain.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to PostStack",
    "status": "delivered",
    "html": "<h1>Hello!</h1><p>Welcome aboard.</p>",
    "text": "Hello! Welcome aboard.",
    "tags": ["welcome"],
    "created_at": "2026-03-23T10:00:00.000Z",
    "sent_at": "2026-03-23T10:00:01.000Z",
    "delivered_at": "2026-03-23T10:00:02.000Z"
  }
}
```

--------------------------------

### POST /subscription-topics

Source: https://poststack.dev/docs/subscription-topics

Create a new subscription topic.

```APIDOC
## POST /subscription-topics

### Description
Create a new subscription topic.

### Method
POST

### Endpoint
/subscription-topics

### Request Body
- **name** (string) - Required - The name of the topic.
- **description** (string) - Required - A description of the topic.

### Request Example
{
  "name": "Product Updates",
  "description": "New features, improvements, and release notes"
}
```

--------------------------------

### GET /domains/:id/dmarc/reports

Source: https://poststack.dev/docs/domains

List aggregated DMARC reports for a specific domain with pagination support.

```APIDOC
## GET /domains/:id/dmarc/reports

### Description
List aggregated DMARC reports for a domain with pagination.

### Method
GET

### Endpoint
/domains/:id/dmarc/reports

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the domain.

### Response
#### Success Response (200)
- **reports** (array) - List of DMARC report summaries.
- **pagination** (object) - Pagination metadata including page, perPage, total, and totalPages.

#### Response Example
{
  "reports": [
    {
      "id": 1,
      "org_name": "google.com",
      "date_range_begin": "2026-03-22T00:00:00.000Z",
      "date_range_end": "2026-03-23T00:00:00.000Z",
      "total_count": 1250,
      "pass_count": 1248,
      "fail_count": 2
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 15,
    "totalPages": 1
  }
}
```

--------------------------------

### Create a new signup form

Source: https://poststack.dev/docs/signup-forms

Defines the structure for a new signup form, including field configurations and post-submission behavior.

```json
{
  "name": "Newsletter Signup",
  "segment_id": "seg_abc123def456",
  "topic_id": "top_xyz789ghi012",
  "fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "placeholder": "you@example.com"
    },
    {
      "name": "first_name",
      "type": "text",
      "label": "First Name",
      "required": false,
      "placeholder": "Jane"
    }
  ],
  "success_message": "Thanks for subscribing!",
  "redirect_url": "https://example.com/welcome"
}
```

--------------------------------

### Configure Claude Desktop for MCP

Source: https://poststack.dev/docs/mcp

JSON configuration for the Claude Desktop application to enable the PostStack MCP server.

```json
{
  "mcpServers": {
    "poststack": {
      "command": "npx",
      "args": ["-y", "@poststack.dev/mcp"],
      "env": {
        "POSTSTACK_API_KEY": "sk_live_..."
      }
    }
  }
}
```

--------------------------------

### GET /contacts/:id

Source: https://poststack.dev/docs/contacts

Retrieve a single contact by ID, including all properties and subscription status.

```APIDOC
## GET /contacts/:id

### Description
Retrieve a single contact by ID, including all properties and subscription status.

### Method
GET

### Endpoint
/contacts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contact.

### Response
#### Success Response (200)
- **contact** (object) - The contact details including properties, subscription status, and timestamps.

### Response Example
{
  "contact": {
    "id": "con_abc123def456ghi789",
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "Smith",
    "properties": {
      "plan": "pro",
      "signed_up": "2026-01-15"
    },
    "unsubscribed": false,
    "created_at": "2026-03-23T10:00:00.000Z",
    "updated_at": "2026-03-23T12:00:00.000Z"
  }
}
```

--------------------------------

### GET /contacts

Source: https://poststack.dev/docs/contacts

List contacts with pagination. Supports search by email or name, and filtering by segment.

```APIDOC
## GET /contacts

### Description
List contacts with pagination. Supports search by email or name, and filtering by segment.

### Method
GET

### Endpoint
/contacts

### Response
#### Success Response (200)
- **data** (array) - List of contact objects.
- **meta** (object) - Pagination metadata including page, perPage, total, and totalPages.

### Response Example
{
  "data": [
    {
      "id": "con_abc123def456ghi789",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "unsubscribed": false,
      "created_at": "2026-03-23T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1250,
    "totalPages": 63
  }
}
```

--------------------------------

### Signup Forms

Source: https://poststack.dev/docs/sdk

Methods for creating and submitting signup forms.

```APIDOC
## poststack.signupForms.create(params)
Creates a new signup form.

## poststack.signupForms.submit(formId, params)
Submits data to a signup form.
```

--------------------------------

### List Mailboxes API Response

Source: https://poststack.dev/docs/mailboxes

Example response containing a list of mailboxes with pagination metadata.

```json
{
  "data": [
    {
      "id": 1,
      "emailAddress": "support@yourdomain.com",
      "displayName": "Support Team",
      "quotaBytes": 1073741824,
      "status": "active",
      "webhookEnabled": true,
      "lastLoginAt": "2026-03-28T15:30:00.000Z",
      "createdAt": "2026-03-28T12:00:00.000Z",
      "domain": { "id": 1, "name": "yourdomain.com" }
    }
  ],
  "meta": { "page": 1, "perPage": 50, "total": 1, "totalPages": 1 }
}
```

--------------------------------

### Create a Subscription Topic

Source: https://poststack.dev/docs/subscription-topics

Define a new category for email subscriptions by providing a name and description.

```json
{
  "name": "Product Updates",
  "description": "New features, improvements, and release notes"
}
```

--------------------------------

### Dynamic segment rule structure

Source: https://poststack.dev/docs/segments

Example of the rule object structure used for dynamic segments.

```json
{
  "rules": {
    "operator": "and",
    "conditions": [
      { "field": "plan", "comparator": "equals", "value": "pro" },
      { "field": "email", "comparator": "contains", "value": "@company.com" }
    ]
  }
}
```
Tokens:
Raw