Transactional email API

1. 01Create a Nextsend project in your Nexthost workspace.
2. 02Add a sending domain and publish every required DNS record.
3. 03Wait until ownership, SPF, DKIM, and return-path are verified.
4. 04Create a production API key and store it immediately.

Send a production key in the Bearer authorization header. Keys are scoped per project, can be restricted to one sending domain, and are displayed only when created. Development keys validate and record requests without entering the live delivery queue.

Authorization: Bearer pi_live_…
Content-Type: application/json
Idempotency-Key: your-stable-request-key

Submit at least one recipient and one text or HTML body. The sender must belong to an active verified domain assigned to the authenticated project.

curl https://api.properinbox.com/v1/email/send \
  -X POST \
  -H "Authorization: Bearer $NEXTSEND_API_KEY" \
  -H "Idempotency-Key: signup-120894" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Example"
    },
    "to": [
      { "email": "[email protected]", "name": "Customer" }
    ],
    "reply_to": { "email": "[email protected]" },
    "subject": "Welcome",
    "text": "Your account is ready.",
    "html": "<p>Your account is ready.</p>",
    "tags": ["onboarding"],
    "metadata": { "account_id": "acct_120894" }
  }'

HTTP/1.1 202 Accepted
{
  "message_id": "pi_msg_…",
  "status": "queued"
}

Reusing an idempotency key with the same request returns the existing message. Reusing it with different content is rejected.

Query a message with a key that has the email.read scope. An MTA acceptance is reported as sent; only a downstream delivery event can advance a message to delivered.

curl https://api.properinbox.com/v1/email/pi_msg_… \
  -H "Authorization: Bearer $NEXTSEND_API_KEY"

Create an SMTP credential in the project console and store the password when it is displayed. Use authenticated TLS submission; do not reuse a mailbox password.

Templates are versioned and encrypted at rest. Define variables with double braces in the subject, text, or HTML—for example {{verification_code}}. Every required variable must be supplied and unknown variables are rejected.

curl https://api.properinbox.com/v1/email/send \
  -X POST \
  -H "Authorization: Bearer $NEXTSEND_API_KEY" \
  -H "Idempotency-Key: verification-120894" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "[email protected]" },
    "to": [{ "email": "[email protected]" }],
    "templateId": "verification_email",
    "variables": {
      "name": "Customer",
      "verification_code": "482913"
    }
  }'

HTML variable values are escaped before rendering. Preview and test-send tools are available in the Nexthost template console.

Nextsend sends JSON events to public HTTPS endpoints. Verify the signature before processing the body, deduplicate by the event ID, and return a 2xx response only after accepting the event.

ProperInbox-Event-ID: pi_evt_…
ProperInbox-Signature: t=1721810400,v1=…

signed_payload = timestamp + "." + raw_request_body
expected = HMAC_SHA256(webhook_secret, signed_payload)

Delivery retries use exponential backoff. Redirects and webhook targets resolving to private network addresses are rejected.