truncus-email

# Truncus Email

Truncus is a transactional email API for delivering alerts, reports, receipts, and notifications. EU-native infrastructure (AWS SES eu-west-1), deterministic delivery with idempotency enforcement and full event tracing.

## When to Use

Use this skill when a workflow needs to send email: system alerts, generated reports, order receipts, password resets, onboarding sequences, monitoring notifications, or any programmatic email delivery.

## Authentication

Truncus uses Bearer token authentication. The API key is read from the `TRUNCUS_API_KEY` environment variable.

**Header format:**

```
Authorization: Bearer <TRUNCUS_API_KEY>
```

API keys use the prefix `tr_live_` followed by 64 hex characters. If the key is missing, malformed, or revoked, the API returns HTTP 401 with an error code (`MISSING_API_KEY`, `INVALID_API_KEY`, or `API_KEY_REVOKED`).

## Send Endpoint

```
POST https://truncus.co/api/v1/emails/send
```

### Required Headers

| Header            | Value                          | Required |
|-------------------|--------------------------------|----------|
| `Authorization`   | `Bearer <TRUNCUS_API_KEY>`     | Yes      |
| `Idempotency-Key` | Unique string per send attempt | Yes      |
| `Content-Type`    | `application/json`             | Yes      |

The `Idempotency-Key` header is **mandatory**. Requests without it receive HTTP 400 with code `MISSING_IDEMPOTENCY_KEY`. If a duplicate key is submitted, the API returns the original message without re-sending (status `duplicate`).

### Required Body Fields

| Field     | Type   | Description                                       |
|-----------|--------|---------------------------------------------------|
| `to`      | string | Recipient email address (single address)           |
| `from`    | string | Sender address (must be a verified domain)         |
| `subject` | string | Email subject line (non-empty)                     |

At least one of `html`, `react`, or `template_id` must be prov...

# truncus-email

OpenClaw skill for sending transactional emails through the Truncus API.

## 5-Second Demo

> **You:** "Send an alert email to ops@acme.com that the staging database is running low on disk space."
>
> **Agent:** Sent email to ops@acme.com with subject "Alert: Staging database disk space low" via Truncus. Message ID: `clxyz123`.

## What It Does

- Sends transactional emails (alerts, reports, receipts, notifications) via a single REST endpoint
- Enforces idempotency on every send to prevent duplicates
- Supports HTML and plain text bodies, attachments, CC/BCC, scheduled sending
- Validates requests locally before calling the API
- Simulates sends when no API key is configured (local dev mode)
- Handles rate limits and retries automatically

## Install

Clone into your OpenClaw skills directory:

```bash
git clone https://github.com/vanmoose/truncus-openclaw-skill.git ~/.openclaw/skills/truncus-email
```

Or add to a workspace:

```bash
git clone https://github.com/vanmoose/truncus-openclaw-skill.git skills/truncus-email
```

No dependencies. No build step. The skill is a single `SKILL.md` file.

## Get an API Key

1. Go to [https://truncus.co](https://truncus.co)
2. Create an account (3,000 emails/month free, no credit card required)
3. Generate an API key with the `send` scope (and `read_events` if you want delivery tracking)
4. Set it in your environment:

```bash
export TRUNCUS_API_KEY="tr_live_your_key_here"
```

## Local Dev Mode

If `TRUNCUS_API_KEY` is not set, the skill simulates email sends without calling the API. It prints the payload that would be sent and returns a mock success. Useful for testing workflows before going live.

## Example Use Cases

- **Monitoring alert**: "Email the on-call team that API latency exceeded 500ms"
- **Generated report**: "Build a weekly revenue summary table and email it to finance@company.com"
- **User notification**: "Send a welcome email to the new signup with their account details"
- **Incident response...