# Djinnletter

> Djinnletter is email delivery for newsletters that an AI agent operates. The agent writes every word and runs the newsletter through a REST API (and an optional CLI): it manages subscribers, tags and contact fields, sends issues to everyone or to tags with merge-tag personalization, builds email sequences started by signups or custom events, connects other tools with webhooks in and out, and reads raw results to report on them. The person approves access, publishes DNS, activates sequences and adds credits in the dashboard.

- Pricing: prepaid, €1 per 1,000 emails (one credit is one email accepted for one recipient). Credits never expire, there is no subscription, and prices exclude VAT. A key can read the balance but never spends money or saves a card.
- Agent-first: there is no hosted newsletter site and no content generation. Content comes from the calling agent; Djinnletter stores it, renders it with a template and delivers it.
- Consent: the customer (the workspace owner) is responsible for having each recipient's consent. Djinnletter never makes an address that unsubscribed, bounced or complained active again, and every email carries a one-click unsubscribe link.
- One workspace is one publication. Each API key belongs to exactly one workspace.

## Start here

- [Setup instructions](https://app.djinnletter.com/setup.md): first-run flow an agent follows to connect, verify the sender, import the audience and send a first issue
- [Agent skill](https://app.djinnletter.com/skill.md): the full operating manual, starting with a "What you can do" capability map
- [llms-full.txt](https://djinnletter.com/llms-full.txt): this summary followed by the whole skill in one file

## API

- [OpenAPI JSON](https://api.djinnletter.com/api/v1/openapi.json): machine-readable contract for every endpoint, with required scopes
- [API docs](https://api.djinnletter.com/api/v1/docs): human-readable API reference
- [Health](https://api.djinnletter.com/health): API status
- API base: `https://api.djinnletter.com/api/v1`, authenticated with `Authorization: Bearer sk_live_...`. Agents without a key start a browser approval with `POST /api/v1/agent-connect`.

## Accounts

- [Dashboard](https://app.djinnletter.com): where the person reviews, activates sequences, manages credits and settings
- [Sign up](https://app.djinnletter.com/register): create an account and its first workspace
- [Log in](https://app.djinnletter.com/login): sign in to an existing account
- [Add credits](https://app.djinnletter.com/usage): prepaid balance, card, auto-recharge and invoices (owner only)

## Capabilities

- [Connect an agent](https://app.djinnletter.com/skill.md#connect-without-pasting-a-key): get a workspace key through browser approval, no pasted secrets
- [Subscribers](https://app.djinnletter.com/skill.md#audience): add, update, list, search, export and unsubscribe people
- [CSV import](https://app.djinnletter.com/skill.md#audience): import a list, with extra columns kept as contact fields
- [CRM sync](https://app.djinnletter.com/skill.md#sync-from-a-crm-upsert): create or update up to 1,000 people per call by email, safe to resend
- [Contact fields](https://app.djinnletter.com/skill.md#contact-fields): keep CRM data on each person and list the keys in use
- [Tags](https://app.djinnletter.com/skill.md#audience): group subscribers and send to one or more tags
- [Signup form](https://app.djinnletter.com/skill.md#workspace-configuration-over-rest): an embeddable form with double opt-in for the person's website
- [Issues](https://app.djinnletter.com/skill.md#assemble-and-deliver-an-issue): draft, preview, test, approve, schedule or send now, to everyone or to tags
- [Body format](https://app.djinnletter.com/skill.md#body-format): subject, preview text and one body with headings, lists, links and images
- [Merge tags](https://app.djinnletter.com/skill.md#personalize-with-merge-tags): `{{first_name|there}}`, `{{name}}`, `{{email}}` and `{{event.*}}`, with a preview as any subscriber
- [Delivery status](https://app.djinnletter.com/skill.md#reconcile-an-ambiguous-send): follow a send and settle an ambiguous one without sending twice
- [Sequences](https://app.djinnletter.com/skill.md#sequences-emails-after-signup): series of emails after a signup, on chosen days, with per-step results
- [Custom events](https://app.djinnletter.com/skill.md#events-start-a-sequence-from-your-site-or-payments): start a sequence from a purchase or any backend event, carrying data, fields and tags
- [Inbound URLs](https://app.djinnletter.com/skill.md#inbound-url-fire-an-event-with-no-server): fire an event from Stripe, Zapier, Make or a hosted shop with no server
- [Outgoing webhooks](https://app.djinnletter.com/skill.md#webhooks-tell-other-tools-what-happened): signed JSON when people join, change, leave, click or finish a sequence
- [Metrics](https://app.djinnletter.com/skill.md#status-metrics-and-billing): delivery, opens, clicks, unsubscribes and top links
- [Raw data exports](https://app.djinnletter.com/skill.md#analyze-results): emails, subscribers, sends, links, tags and events as JSONL or CSV to analyze
- [Templates and brand](https://app.djinnletter.com/skill.md#workspace-configuration-over-rest): starter or custom templates, logo, images and brand color
- [Sender domains](https://app.djinnletter.com/skill.md#sender-domains): add a domain, get its DNS records and verify it
- [Workspaces and keys](https://app.djinnletter.com/skill.md#workspace-configuration-over-rest): setup checklist, newsletter name and sender, API keys and scopes
- [Billing](https://app.djinnletter.com/skill.md#status-metrics-and-billing): read the prepaid balance, a VAT preview and invoices
- [Errors and idempotency](https://app.djinnletter.com/skill.md#errors): error codes, retries and `Idempotency-Key` replays