Send with the API

The email API is the recommended path for transactional product email. It accepts JSON, authenticates with a Parcel Wing API key, and returns queued message records per recipient.

Request shape

Send a POST request to /api/emails with a bearer API key. Provide a verified from address, one recipient or up to 50 recipients, a subject, and either text or html. If only HTML is provided, Parcel Wing derives a plain-text fallback.

send-email.sh

curl https://parcelwing.com/api/emails \
  -X POST \
  -H "Authorization: Bearer pw_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": "[email protected]",
    "subject": "Your receipt is ready",
    "text": "Thanks for your order. Your receipt is attached in your account.",
    "html": "<p>Thanks for your order. Your receipt is ready in your account.</p>",
    "reply_to": "[email protected]",
    "tags": {
      "workflow": "receipt",
      "plan": "launch"
    }
  }'

Response shape

Successful API requests return 202 Accepted with a list of queued email records. Parcel Wing creates a separate message for each recipient so every recipient can have its own delivery trail, suppression decision, and lifecycle events.

response.json

{
  "object": "list",
  "data": [
    {
      "object": "email",
      "id": "7b3f1a2e-1f6f-4d65-9c4e-3e3b0f2d7a11",
      "to": "[email protected]",
      "status": "queued"
    }
  ]
}

Screenshot placeholder

API-created message in Emails

Capture the Emails list filtered to an API-created message showing status, recipient, sender, subject, and message source or metadata if visible.

Replace this placeholder with a product screenshot during the follow-up screenshot pass.

Templates

You can send from a saved template by passing either template_id or template_alias. Do not pass both. Parcel Wing looks up the active template, loads the brand kit, renders the subject and HTML, derives text, and stores template metadata on the message.

send-template.sh

curl https://parcelwing.com/api/emails \
  -X POST \
  -H "Authorization: Bearer pw_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": "[email protected]",
    "template_alias": "welcome_email",
    "template_params": {
      "first_name": "Ada",
      "workspace_name": "Acme"
    }
  }'

Errors

Validation errors return a structured API error. Suppression and reputation guardrails return conflict responses so your application can stop retrying until the underlying issue is resolved. Infrastructure or content problems are returned as send failures and recorded on the message when a message record was created.