Postmark

Postmark is a transactional email service with industry-leading deliverability. Use it to send order confirmations, password resets, notifications, and other critical emails.

Setup

Add your Postmark credentials to your environment variables:

# .env
POSTMARK_API_TOKEN=...
POSTMARK_FROM_EMAIL=noreply@example.com
POSTMARK_FROM_NAME="Your App Name"

Get your API token from the Postmark Dashboard.

Sending emails

capabilityId: send-email
provider:
  type: postmark
  operation: sendEmail

inputs:
  to:
    type: string
    description: "Recipient email address"
  subject:
    type: string
  htmlBody:
    type: string
    optional: true
  textBody:
    type: string
    optional: true
  templateId:
    type: string
    optional: true
  templateData:
    type: object
    optional: true

outputs:
  messageId:
    type: string
  submittedAt:
    type: timestamp

Using templates

Postmark templates allow you to design emails in their dashboard and populate them with data:

capabilityId: send-welcome-email
provider:
  type: postmark
  operation: sendEmail

inputs:
  to:
    type: string
  userName:
    type: string

config:
  templateId: "welcome-email"
  templateData:
    user_name: ${input.userName}
    login_url: "https://app.example.com/login"

Webhooks

Postmark can notify your app about delivery, bounces, and opens:

https://your-app.com/api/webhooks/postmark

ContractSpec automatically processes these webhook events:

• Delivery – Email was successfully delivered
• Bounce – Email bounced (hard or soft)
• SpamComplaint – Recipient marked email as spam
• Open – Recipient opened the email
• Click – Recipient clicked a link

Best practices

• Use templates for consistent branding
• Always provide both HTML and plain text versions
• Monitor bounce rates and remove invalid addresses
• Use message streams to separate different email types
• Test emails in the Postmark sandbox before going live
• Set up DKIM and SPF records for your domain