Newsletters
Newsletters are the core output of Abstractions. Each one is an AI-generated summary of your repository's recent commits and pull requests, formatted as an email and sent to your subscribers.
Generating a newsletter
- Open a repository and go to Newsletters
- Click Generate
- Abstractions drafts a newsletter from recent activity not yet covered by a previous issue
- The draft opens automatically once generation is complete
Generation usually takes 30–60 seconds depending on the volume of activity and the model you've configured.
If there's no new activity since the last newsletter, generation may produce a short or empty draft. Check your repository's indexing status first.
Reviewing and editing a draft
The newsletter detail page shows a live preview of the email. You can:
- Edit the HTML directly — click Edit to open the source editor; the preview updates as you type
- Save changes — click Save before sending if you've made edits
Make your edits before sending. Once a newsletter is sent, the content is final.
Sending a newsletter
After reviewing the draft:
- Click Send
- Confirm the send in the dialog
Abstractions sends the email to all configured recipients — workspace members (if enabled) and any additional addresses you've added in repository settings.
Scheduled sends
If you've configured a send day and time in repository settings, Abstractions will generate and send newsletters automatically on that schedule. You don't need to trigger them manually.
Scheduled newsletters are generated from activity since the last sent issue. If there's nothing new to report, the scheduled send is skipped.
Viewing sent newsletters
All sent newsletters appear in the Newsletters tab for each repository. Each entry shows the send date, recipient count, and open rate.
You can open any sent newsletter to view its content and delivery stats.
How it works
Newsletter statuses
Every newsletter record moves through a defined lifecycle:
| Status | What it means |
|---|---|
| Queued | The job has been created and is waiting for a worker to pick it up |
| Processing | A worker has started — topic selection and content generation are in progress |
| Sent | Generation completed and the email was delivered to all recipients |
| Error | Something failed during generation or delivery; the error message is saved on the record |
If a newsletter is stuck in Queued or Processing for more than a few minutes, the most common cause is an AI provider error — check your API key and quota.
The generation pipeline
When you click Generate (or the scheduler fires), this is what runs:
- Topic selection — Abstractions picks the next topic from your queue. If the queue is empty, it auto-generates up to 5 topics from recent file activity before continuing.
- Embedding + retrieval — The topic title is embedded using your configured model. Abstractions then queries all stored chunk embeddings for that repository and retrieves the 12 most semantically similar chunks.
- Content generation — The retrieved chunks (file summaries and code context) are passed to your generation model, which writes the newsletter section for that topic.
- Email assembly — The generated content is wrapped in the standard email template with your repository name, a link to GitHub, and a footer explaining why recipients are receiving it.
- Delivery — The assembled HTML is sent to all configured recipients via SES. The newsletter record is stamped
sentand the topic is marked as covered.
Scheduled send mechanics
The scheduler runs every hour and checks which repositories have a matching send_day and send_hour (stored in UTC). For each match, it applies a 20-hour double-send guard — if a newsletter was already sent within the last 20 hours for that repository, the scheduled send is skipped. This prevents duplicate issues if the scheduler fires multiple times around an hour boundary.
Send times in the UI are shown and accepted in your local timezone; they're converted to UTC on save.
Troubleshooting
Generate button is disabled — make sure your AI provider is configured in AI settings and the repository has finished its initial index.
Newsletter is empty or low quality — this usually means the repository has little recent activity, or the indexing model didn't extract enough signal. Try triggering a manual index and generating again.
Recipients didn't receive the email — check the additional recipients list in repository settings for typos. Also confirm that workspace members are enabled as recipients if you're relying on that.
Next steps
- Topics — queue up subjects to guide future newsletter content
- Repositories — configure schedule and recipient settings