SNDR

https://www.sndr.sh/docs
Admin
SNDR is an email infrastructure platform that enables developers to send emails, manage sending...
Tokens:2,047
Snippets:44
Trust Score:2.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @rkiza/sndr SDK

Source: https://www.sndr.sh/docs/quickstart

Install the Sndr SDK using npm. The SDK is a lightweight wrapper compatible with Node 18+, Bun, Deno, and edge environments.

```bash
npm install @rkiza/sndr
```

--------------------------------

### GET /v1/emails

Source: https://www.sndr.sh/docs/api-reference

Retrieves a paginated list of sent emails.

```APIDOC
## GET /v1/emails

### Description
List sent emails. Paginated.
```

--------------------------------

### GET /v1/emails/:id

Source: https://www.sndr.sh/docs/api-reference

Retrieves the details of a specific email by its unique identifier.

```APIDOC
## GET /v1/emails/:id

### Description
Retrieve a single email by ID.
```

--------------------------------

### POST /v1/api-keys

Source: https://www.sndr.sh/docs/api-reference

Generates a new API key. The full key is returned only once upon creation.

```APIDOC
## POST /v1/api-keys

### Description
Create an API key. The full key is returned once.
```

--------------------------------

### POST /v1/templates

Source: https://www.sndr.sh/docs/api-reference

Creates a new versioned email template.

```APIDOC
## POST /v1/templates

### Description
Create a template. Templates are versioned.
```

--------------------------------

### Send email with Sndr SDK

Source: https://www.sndr.sh/docs/quickstart

Initialize the Sndr client with your API key and use the emails.send method to dispatch an email.

```js
import { Sndr } from '@rkiza/sndr';

const sndr = new Sndr(process.env.SNDR_API_KEY!);

const { id } = await sndr.emails.send({
  from: 'hello@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Welcome aboard',
  html: '<p>Thanks for joining us.</p>',
});
```

--------------------------------

### Send an email with cURL

Source: https://www.sndr.sh/docs/getting-started

Use this cURL command to send your first email via the SNDR API. Replace the Authorization header with your generated API key and ensure the 'from' address matches your verified domain.

```bash
curl -X POST 'https://api.sndr.sh/v1/send' \
  -H 'Authorization: Bearer sndr_live_x9k2...' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Hello, world",
    "html": "<p>You did it.</p>"
  }'
```

--------------------------------

### POST /v1/webhooks

Source: https://www.sndr.sh/docs/api-reference

Registers a new webhook endpoint and returns the signing secret.

```APIDOC
## POST /v1/webhooks

### Description
Register a webhook endpoint. Returns the signing secret.
```

--------------------------------

### POST /v1/domains

Source: https://www.sndr.sh/docs/api-reference

Adds a new sending domain and returns the required DNS records.

```APIDOC
## POST /v1/domains

### Description
Add a sending domain. Returns DNS records.
```

--------------------------------

### Send email without SDK using fetch

Source: https://www.sndr.sh/docs/quickstart

Send an email by making a direct POST request to the Sndr HTTPS API. This approach requires manual handling of headers and JSON serialization.

```js
const res = await fetch('https://api.sndr.sh/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SNDR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'hello@yourdomain.com',
    to: ['customer@example.com'],
    subject: 'Welcome aboard',
    html: '<p>Thanks for joining us.</p>',
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { id } = await res.json();
```

--------------------------------

### POST /v1/send

Source: https://www.sndr.sh/docs/api-reference

Sends an email. This operation is idempotent if an Idempotency-Key header is provided.

```APIDOC
## POST /v1/send

### Description
Send an email. Idempotent if the Idempotency-Key header is supplied.
```

--------------------------------

### Authentication Header

Source: https://www.sndr.sh/docs/api-reference

All API requests must include a Bearer token in the Authorization header. Tokens are specific to either the live or test environment and an organisation.

```bash
Authorization: Bearer sndr_live_x9k2...
```

--------------------------------

### Verifying Webhook Signatures

Source: https://www.sndr.sh/docs/webhooks

This snippet demonstrates how to verify the authenticity of a webhook payload using the X-Sndr-Signature header and the endpoint secret.

```APIDOC
## Verifying Webhook Signatures

### Description
Every webhook payload is signed with HMAC-SHA256 using the secret of the endpoint that received it. The signature is included in the `X-Sndr-Signature` header.

### Verification Logic
```javascript
import { createHmac } from 'crypto';

function verify(req, secret) {
  const sig = req.headers['x-sndr-signature'];
  const expected = createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return sig === expected;
}
```
```

--------------------------------

### Verify X-Sndr-Signature with Node.js

Source: https://www.sndr.sh/docs/webhooks

Use the HMAC-SHA256 algorithm to verify the authenticity of a webhook payload by comparing the X-Sndr-Signature header against a locally generated hash using your endpoint secret.

```javascript
import { createHmac } from 'crypto';

function verify(req, secret) {
  const sig = req.headers['x-sndr-signature'];
  const expected = createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return sig === expected;
}
```

--------------------------------

### Error Response Structure

Source: https://www.sndr.sh/docs/errors

The standard format for error responses returned by the SNDR API.

```APIDOC
## Error Response Format

### Description
When an API request fails, the server returns a standard HTTP status code and a JSON body containing details about the error.

### Response Body
- **error** (object) - The root error object
  - **code** (string) - A machine-readable error code (e.g., "invalid_recipient")
  - **message** (string) - A human-readable explanation of the error
  - **request_id** (string) - A unique identifier for the request, useful for support

### Response Example
```json
{
  "error": {
    "code": "invalid_recipient",
    "message": "Recipient \"not-an-email\" is not a valid address",
    "request_id": "req_8a91lk2"
  }
}
```
```

--------------------------------

### Structured Error Envelope

Source: https://www.sndr.sh/docs/errors

The standard JSON format returned by SNDR when an error occurs, including the error code, message, and request ID.

```json
{
  "error": {
    "code": "invalid_recipient",
    "message": "Recipient \"not-an-email\" is not a valid address",
    "request_id": "req_8a91lk2"
  }
}
```
Tokens:
Raw