Sign in to fill these examples with your own keys. Sign in Start free trial

Custom headers

Add headers. Reserved names are ignored.

Add your own headers to a REST send with the headers object. PostShiba copies each name and value onto the composed mail, except for reserved names.

Add a header

send-with-headers.sh
1curl -sS -X POST \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 -H 'Content-Type: application/json' \ 4 -d '{ 5 "from": "hello@mail.example.com", 6 "to": ["you@example.com"], 7 "subject": "PostShiba test", 8 "text": "hello from PostShiba", 9 "headers": { 10 "X-Campaign": "cmp_123" 11 } 12 }' \ 13 https://app.postshiba.com/api/v1/emails

On the dashboard test-send form, the same object goes in Headers under More.

Rules

  • Names must be RFC 5322 field names: printable ASCII with no space or colon. Any other name fails the whole send with 422 {error: invalid, field: headers}.
  • Values are written as strings. Blank values are dropped.
  • A value that contains a line break (CR or LF) is ignored.
  • Reserved names are ignored, in any case. _ counts as -, so return_path is Return-Path.

Reserved header names

Group Names
Addressing and body From, To, Cc, Bcc, Subject, Reply-To, Date, MIME-Version, any Content-*
Envelope and trace Return-Path, Sender, Received, Authentication-Results, DKIM-Signature, any Resent-*
Set by PostShiba X-Report-Abuse, Feedback-ID, X-Mailer, X-Complaints-To, X-Tenant-Id, X-PostShibaRef, any X-Capsule-* except X-Capsule-Ip and X-Capsule-Pool

List-Unsubscribe, List-Unsubscribe-Post, List-Id, In-Reply-To, References, Message-ID, Precedence, Auto-Submitted, and your own X-* headers are kept.

Use the top-level from, to, cc, bcc, subject, and reply_to fields instead of headers for addressing. PostShiba writes the abuse-report headers itself. See How do I report abuse?.

To pin a sending cluster, set X-Capsule-Cluster-Id as an HTTP request header on POST /api/v1/emails, not in headers. See Sending.

  • For fields that should come back on delivery webhooks, use unique args.
  • To send one message from a specific sending IP on its cluster, set X-Capsule-Ip. To send from one of your IP pools attached to the cluster, set X-Capsule-Pool to the pool's name. PostShiba removes both before the message leaves. See How do dedicated IPs work?.
  • For one-click List-Unsubscribe and X-Include-Unsubscribe, see How do recipients unsubscribe?.

Next steps