Skip to content

Headers and metadata

Add application context without replacing the headers Prawnwire owns.

POST/v1/email

Custom headers

Headers is an array of { "Name": "...", "Value": "..." } objects. Both fields must be strings.

Names contain 1 to 100 ASCII letters, digits, or hyphens. Values are a single line of at most 1,000 characters; carriage returns and line feeds are refused. Invalid or reserved headers return ErrorCode 300.

Refused headers

The following names are reserved, case-insensitively:

From
To
Cc
Bcc
Subject
Date
Message-ID
Reply-To
Sender
Return-Path
Received
DKIM-Signature
MIME-Version
Content-Type
Content-Transfer-Encoding

Use ReplyTo for reply routing and the message’s own From, To, Cc, Bcc and Subject fields. Prawnwire writes Date, Message-ID, MIME and signing headers.

Metadata

Metadata is a JSON object with at most 10 fields. Keys are 1 to 20 characters. Values become strings of at most 80 characters.

Use strings for predictable results. Numbers and booleans are accepted and converted with JavaScript’s string conversion. Objects, arrays, and null values are refused. Metadata is returned in activity and message details; it is not a custom email header.

Avoid secrets and unnecessary personal data. A key with email:read can read metadata.

Tags

Tag is an optional string of up to 1,000 characters. Use a stable value such as welcome or receipt, then filter Messages by that value. Tag matching is exact.

https://api.prawnwire.com/v1

curl 'https://api.prawnwire.com/v1/email' \
  -H "Authorization: Bearer $PRAWNWIRE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "From": "hello@yourdomain.com",
  "To": "ada@example.com",
  "Subject": "Welcome to your account",
  "TextBody": "Hi Ada, your account is ready.",
  "Tag": "welcome",
  "Metadata": {
    "account_id": "acct_1042"
  },
  "Headers": [
    {
      "Name": "X-Campaign",
      "Value": "welcome"
    }
  ]
}'

const response = await fetch(
  'https://api.prawnwire.com/v1/email',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.PRAWNWIRE_API_KEY,
      'Content-Type': 'application/json',
    },    
    body: JSON.stringify({
  "From": "hello@yourdomain.com",
  "To": "ada@example.com",
  "Subject": "Welcome to your account",
  "TextBody": "Hi Ada, your account is ready.",
  "Tag": "welcome",
  "Metadata": {
    "account_id": "acct_1042"
  },
  "Headers": [
    {
      "Name": "X-Campaign",
      "Value": "welcome"
    }
  ]
}),
  },
)

const result = await response.json()
if (!response.ok) throw new Error(JSON.stringify(result))
console.log(result)

The prawnwire SDK is publishing soon. This example uses built-in fetch in Node 18 or newer.

import postmark from 'postmark'

const client = new postmark.ServerClient(
  process.env.PRAWNWIRE_API_KEY,
  { requestHost: 'api.prawnwire.com/v1' },
)

const result = await client.sendEmail({
  "From": "hello@yourdomain.com",
  "To": "ada@example.com",
  "Subject": "Welcome to your account",
  "TextBody": "Hi Ada, your account is ready.",
  "Tag": "welcome",
  "Metadata": {
    "account_id": "acct_1042"
  },
  "Headers": [
    {
      "Name": "X-Campaign",
      "Value": "welcome"
    }
  ]
})
console.log(result)

POST /v1/email · Keep your API key on the server.

Response · HTTP 200

{
  "To": "ada@example.com",
  "SubmittedAt": "2026-10-11T11:18:00.377Z",
  "MessageID": "d0706314-5a78-4583-a3f7-121dbf982b56",
  "ErrorCode": 0,
  "Message": "OK"
}