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

Sending emails

What you can send today, and how it is queued.

A send is one message queued on a cluster. This page compares the three ways to send and lists the checks every send passes first.

Pick a send path

Path Endpoint Auth Best for
SMTP smtp.postshiba.com:587, STARTTLS AUTH PLAIN with an SMTP credential High volume, existing mail libraries
HTTP inject POST https://inject.postshiba.com/api/inject/v1 HTTP Basic with an SMTP credential High volume over HTTP
REST POST /api/v1/emails or POST /api/v1/teams/:obfuscated_team_id/clusters/:obfuscated_cluster_id/sends Bearer API key Lower-volume transactional mail. PostShiba composes the MIME for you.

POST /api/v1/emails picks a cluster for you. Set the X-Capsule-Cluster-Id header to pin one. POST /sends always targets the cluster in the path. Field details are on Sending.

For REST, give each app a Send only key. It can call both send endpoints and nothing else. See Create an API key.

Send a message

send.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 }' \ 10 https://app.postshiba.com/api/v1/emails
response.json
1{ 2 "queued": true, 3 "message_id": "abc@capsule.test", 4 "from": "hello@mail.example.com", 5 "to": ["you@example.com"], 6 "subject": "PostShiba test", 7 "unique_args": {} 8}

To send a stored design instead of html and text, see Send with a template.

What every send must pass

PostShiba checks each send in this order. The first failure stops it.

  1. The body has a From and at least one recipient (invalid). A blank From becomes hello@ your first sending-ready domain.
  2. The From address is on a verified sending domain that is not suspended (domain_unverified, domain_suspended).
  3. The cluster has a live SMTP credential for the tenant (credential_missing).
  4. At least one recipient is not suppressed (suppressed). Suppressed recipients are skipped and listed in suppressed on the response.
  5. Your team has production approval, or every recipient is a teammate, a live inbox, or an inbox forward-to address (kyc_required). See Does PostShiba require production approval?.
  6. No recipient fails the email firewall (firewall).
  7. Attachments follow the REST rules (invalid).
  8. The cluster is under its caps (throttled). See What happens at your cap.

Status codes for each error are on Errors.

Next steps