Authentication

PostaSend uses API keys to authenticate requests. You can create and manage API keys from the PostaSend dashboard.

API Keys

All API requests must include your API key in the Authorization header as a Bearer token. API keys are prefixed with ps_live_ for production and ms_test_ for test mode. Test mode keys only send to verified email addresses and do not count towards your monthly quota.

typescript

// Initialize the client with your API key
import { PostaSend } from 'postasend';

const client = new PostaSend({
  apiKey: process.env.POSTASEND_API_KEY!,
  // Optional: switch to test mode
  // mode: 'test',
});

Scoped API Keys

For production use, create scoped API keys with only the permissions your integration needs. Scoped keys reduce the blast radius if a key is ever compromised. Available scopes include emails:send, emails:read, templates:manage, domains:manage, and webhooks:manage.

typescript

// Scoped keys work exactly like full keys
// but are restricted to their granted permissions
const client = new PostaSend({
  apiKey: process.env.POSTASEND_SEND_KEY!, // emails:send scope only
});

// This will succeed
await client.emails.send({ ... });

// This will throw a 403 PermissionError
// await client.templates.list();

Rotating API Keys

If a key is ever exposed, immediately rotate it in the dashboard under Settings → API Keys. Creating a new key does not automatically invalidate the old one — you must explicitly revoke it. After revocation, any requests using the old key will receive a 401 Unauthorized response.

Request Signing (Webhooks)

Webhook requests from PostaSend are signed with HMAC-SHA256 using your webhook secret. Always verify the signature before processing webhook payloads to prevent spoofed requests.

typescript

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Sending Email →