# Notifuse Documentation

- [Welcome to Notifuse](https://docs.notifuse.com/index.md): Notifuse is a modern emailing platform for businesses that want complete control over their email infrastructure. Whether you're sending marketing campaigns, transactional emails, or building notification systems, Notifuse provides the tools and flexibility you need.
- [Workspaces](https://docs.notifuse.com/features/workspaces.md): Workspaces are the foundational organizational unit in Notifuse. They provide a complete, isolated environment for managing your email marketing operations, making it easy to separate different projects, clients, or business units.
- [Contacts](https://docs.notifuse.com/features/contacts.md): Contacts are the foundation of your email marketing efforts in Notifuse. They represent your subscribers, customers, and prospects, complete with detailed profiles, custom fields, and engagement history.
- [Lists](https://docs.notifuse.com/features/lists.md): Lists in Notifuse are organized collections of contacts that allow you to segment your audience and send targeted email campaigns. They provide the foundation for effective email marketing by enabling precise audience targeting and personalized messaging.
- [Templates](https://docs.notifuse.com/features/templates.md): Templates in Notifuse are the foundation of your email design system. They provide reusable, responsive email layouts that can be personalized with dynamic content using Liquid templating and built with MJML components for perfect cross-client compatibility.
- [Broadcast campaigns](https://docs.notifuse.com/features/broadcast-campaigns.md): Broadcast campaigns in Notifuse are mass email marketing initiatives that allow you to send targeted messages to a contact list. They provide powerful features for audience targeting with segment filters, A/B testing, UTM tracking, and flexible scheduling options to deliver the right message to the…
- [Transactional API](https://docs.notifuse.com/features/transactional-api.md): The Transactional API enables you to send event-driven emails directly from your application. Unlike broadcast campaigns, transactional emails are sent individually to specific contacts in real-time with automatic contact management, making them perfect for user-triggered notifications and automated…
- [Custom Events & Goals](https://docs.notifuse.com/features/custom-events.md): Track user behavior and conversion goals to build RFM segments and enrich contact timelines.
- [Setup](https://docs.notifuse.com/web-analytics/setup.md): Install the tracking snippet and configure cookieless website analytics for your workspace.
- [Reports](https://docs.notifuse.com/web-analytics/reports.md): Read the dashboard, explore any dimension, and watch traffic arrive live.
- [Goals](https://docs.notifuse.com/web-analytics/goals.md): Record conversions from your website and use them in segments and automations.
- [Attribution](https://docs.notifuse.com/web-analytics/attribution.md): Classify traffic into channels with rules you control, and rewrite history when you change them.
- [Identifying Visitors](https://docs.notifuse.com/web-analytics/identifying-visitors.md): Tie a website visit to a contact, and use browsing behaviour in segments.
- [Annotations](https://docs.notifuse.com/web-analytics/annotations.md): Mark the moments that explain a chart — a launch, a campaign, an outage.
- [Analytics Assistant](https://docs.notifuse.com/web-analytics/ai-assistant.md): Ask questions about your traffic, get a written summary of a period, and let the assistant drive the dashboard.
- [Automations](https://docs.notifuse.com/features/automations.md): Create automated workflows that trigger based on contact behavior and events
- [Setup](https://docs.notifuse.com/blog/setup.md): Enable and configure the blog feature for your workspace.
- [Theme](https://docs.notifuse.com/blog/theme.md): Customize your blog appearance with Liquid templates.
- [Blog Posts](https://docs.notifuse.com/blog/posts.md): Create and manage blog posts with categories, scheduling, and SEO.
- [AI Assistant](https://docs.notifuse.com/features/ai-assistant.md): One assistant across the email builder, the blog editor and Web Analytics — writing content, editing templates, and answering questions about your traffic.
- [File Manager](https://docs.notifuse.com/features/file-manager.md): The file manager connects to your S3-compatible bucket to store and serve files and images used in your email templates. You can optionally configure a CDN endpoint to customize S3 URLs for better performance.
- [Webhooks](https://docs.notifuse.com/features/webhooks.md): Receive real-time HTTP callbacks when events occur in your workspace.
- [Logs](https://docs.notifuse.com/features/logs.md): Real-time logs for monitoring email delivery and debugging email provider issues. Track message events, webhook data and the workspace audit trail with advanced filtering capabilities.
- [Audit logs](https://docs.notifuse.com/features/audit-logs.md): Who did what in a workspace: members, permissions, API keys, integrations, settings and content changes, with the address it came from and whether it was allowed. Append-only, exportable, with a retention you control.
- [Admins & API Keys](https://docs.notifuse.com/features/admins-api-keys.md): Invite admins and create API keys scoped to exactly the parts of your workspace they need. Choose the permissions a key carries, change them at any time, and understand what each permission really allows.
- [Notification Center](https://docs.notifuse.com/features/notification-center.md): The Notification Center is a mobile-first interface that Notifuse automatically renders when users click on unsubscribe links in newsletters. It provides a seamless experience for contacts to manage their email subscription preferences across all public lists.
- [Newsletter Form Input](https://docs.notifuse.com/tutorials/newsletter-form-input.md): This tutorial will guide you through creating a newsletter subscription form and integrating it with Notifuse to collect and manage subscriber contacts
- [Anthropic](https://docs.notifuse.com/integrations/anthropic.md): Configure Anthropic Claude AI to power blog content creation and email generation in Notifuse.
- [OpenAI](https://docs.notifuse.com/integrations/openai.md): Configure OpenAI to power blog content creation and email generation in Notifuse.
- [Google Gemini](https://docs.notifuse.com/integrations/gemini.md): Configure Google Gemini to power blog content creation and email generation in Notifuse.
- [Firecrawl](https://docs.notifuse.com/integrations/firecrawl.md): Configure Firecrawl to give the AI agent web access for research and content generation.
- [Supabase](https://docs.notifuse.com/integrations/supabase.md): Integrate Supabase Auth with Notifuse for authentication emails and user sync.
- [Zapier](https://docs.notifuse.com/integrations/zapier.md): Connect Notifuse to Zapier: send your transactional emails from any app, trigger Zaps from contact, list and segment events, and add or subscribe contacts.
- [Mailgun](https://docs.notifuse.com/integrations/mailgun.md): Configure Mailgun as your email provider in Notifuse.
- [Amazon SES](https://docs.notifuse.com/integrations/amazon-ses.md): Configure Amazon SES as your email provider in Notifuse.
- [Postmark](https://docs.notifuse.com/integrations/postmark.md): Configure Postmark as your email provider in Notifuse.
- [SendGrid](https://docs.notifuse.com/integrations/sendgrid.md): Configure SendGrid as your email provider in Notifuse.
- [SparkPost](https://docs.notifuse.com/integrations/sparkpost.md): Configure SparkPost as your email provider in Notifuse.
- [Mailjet](https://docs.notifuse.com/integrations/mailjet.md): Configure Mailjet as your email provider in Notifuse.
- [SMTP](https://docs.notifuse.com/integrations/smtp.md): Configure SMTP as your email provider in Notifuse with Basic Auth or OAuth2.
- [Self-hosted Installation](https://docs.notifuse.com/self-hosting/installation.md): How to self-host Notifuse
- [Licence keys](https://docs.notifuse.com/self-hosting/licence.md): Self-hosting Notifuse is free. Six capabilities need a licence key. This page says which, what a key costs, how to install one, and what happens without it.
- [Single Sign-On (OIDC)](https://docs.notifuse.com/self-hosting/sso.md): Let users sign in to Notifuse with your identity provider (Google Workspace, Keycloak, Okta, …) using OpenID Connect, alongside magic-code login.
- [Changing your domain](https://docs.notifuse.com/self-hosting/changing-domain.md): Move a Notifuse instance to a new address, and open the console on workspace custom domains.
- [Root user programmatic signin](https://docs.notifuse.com/api-reference/authentication/root-user-programmatic-signin.md): Authenticates the root user using HMAC signature for programmatic access. This endpoint is designed for automation scenarios like Infrastructure-as-Code deployments, CI/CD pipelines, and automated testing where magic link authentication is impractical.
- [Send a transactional notification](https://docs.notifuse.com/api-reference/send-a-transactional-notification.md): Sends a transactional notification to a contact through specified channels. Requires authentication.
- [List contacts with filtering and pagination](https://docs.notifuse.com/api-reference/list-contacts-with-filtering-and-pagination.md): Retrieves a paginated list of contacts with optional filtering. All contact fields are always returned.
- [Count contacts in a workspace](https://docs.notifuse.com/api-reference/count-contacts-in-a-workspace.md): Returns the total number of contacts in a workspace.
- [Create or update a contact](https://docs.notifuse.com/api-reference/create-or-update-a-contact.md): Creates a new contact or updates an existing one. Contacts are matched **by email address only** — the email is the contact's unique identifier. `external_id` is stored but never used for matching, so sending an existing `external_id` with a new email address creates a second contact.
- [Get a contact by email address](https://docs.notifuse.com/api-reference/get-a-contact-by-email-address.md): Retrieves a contact by their email address within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained).
- [Get a contact by external ID](https://docs.notifuse.com/api-reference/get-a-contact-by-external-id.md): Retrieves a contact by their external ID within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained).
- [Batch import contacts](https://docs.notifuse.com/api-reference/batch-import-contacts.md): Creates or updates multiple contacts in a single batch operation. This is significantly more efficient than individual upsert operations. Optionally subscribes all contacts to specified lists.
- [Delete a contact](https://docs.notifuse.com/api-reference/delete-a-contact.md): Deletes a contact from the workspace by email address. This action is permanent and cannot be undone.
- [Update contact list subscription status](https://docs.notifuse.com/api-reference/update-contact-list-subscription-status.md): Updates the subscription status of a contact in a specific list. Can set status to active, pending, unsubscribed, bounced, or complained.
- [Subscribe to email lists](https://docs.notifuse.com/api-reference/subscribe-to-email-lists.md): Subscribe a contact to one or more email lists. This is a public endpoint that doesn't require authentication.
- [Subscribe to email lists (authenticated)](https://docs.notifuse.com/api-reference/subscribe-to-email-lists-authenticated.md): Subscribe a contact to one or more email lists. This is an authenticated endpoint that requires a bearer token.
- [Import custom events](https://docs.notifuse.com/api-reference/import-custom-events.md): Imports multiple custom events in a single batch operation. Maximum 50 events per request. Auto-creates contacts if they don't exist.
- [Ingest a web analytics beat](https://docs.notifuse.com/api-reference/web-analytics/ingest-a-web-analytics-beat.md): Public collect endpoint used by the Notifuse Analytics browser SDK. Each beat carries the full cumulative session state (all pageviews and goals), so the server can rebuild the session from any single payload. Beats are typically sent as text/plain to avoid CORS preflights; the body is JSON regardle…
- [Replace the workspace's web analytics settings](https://docs.notifuse.com/api-reference/web-analytics/replace-the-workspaces-web-analytics-settings.md): Gated by the web_analytics write permission (like blog settings, members manage the feature without workspace write access). The attribution filters version is recomputed server-side. Passing null settings clears the configuration.
- [Start an attribution backfill](https://docs.notifuse.com/api-reference/web-analytics/start-an-attribution-backfill.md): Rewrites historical web_sessions and web_goals rows with the current attribution rules, one monthly partition per step. Fails while a run is already pending or running.
- [Get the latest backfill run](https://docs.notifuse.com/api-reference/web-analytics/get-the-latest-backfill-run.md)
- [Cancel the in-flight backfill run](https://docs.notifuse.com/api-reference/web-analytics/cancel-the-in-flight-backfill-run.md)
- [List annotations](https://docs.notifuse.com/api-reference/web-analytics/list-annotations.md): Returns the workspace's annotations, most recent moment first. Every filter is optional; with none the most recent 100 rows come back.
- [Get an annotation](https://docs.notifuse.com/api-reference/web-analytics/get-an-annotation.md): Retrieves a single annotation by ID. Requires the web_analytics read permission.
- [Create an annotation](https://docs.notifuse.com/api-reference/web-analytics/create-an-annotation.md): Creates a manual annotation. Requires the web_analytics write permission.
- [Update an annotation](https://docs.notifuse.com/api-reference/web-analytics/update-an-annotation.md): Edits an annotation's moment, timezone and presentation. Requires the web_analytics write permission.
- [Delete an annotation](https://docs.notifuse.com/api-reference/web-analytics/delete-an-annotation.md): Deletes an annotation, automatic ones included — a broadcast annotation cannot come back by accident, since its broadcast has already started. Requires the web_analytics write permission.
- [List broadcasts](https://docs.notifuse.com/api-reference/list-broadcasts.md): Retrieves a list of broadcasts with pagination and optional filtering by status. Supports fetching template details for each variation.
- [Get a broadcast](https://docs.notifuse.com/api-reference/get-a-broadcast.md): Retrieves a single broadcast by ID. Optionally includes template details for each variation.
- [Create a broadcast](https://docs.notifuse.com/api-reference/create-a-broadcast.md): Creates a new broadcast campaign in draft status.
- [Update a broadcast](https://docs.notifuse.com/api-reference/update-a-broadcast.md): Updates an existing broadcast. Only broadcasts in draft, scheduled, or paused status can be updated.
- [Schedule a broadcast](https://docs.notifuse.com/api-reference/schedule-a-broadcast.md): Schedules a broadcast for sending either immediately or at a specified time. This endpoint is restricted in demo mode.
- [Pause a broadcast](https://docs.notifuse.com/api-reference/pause-a-broadcast.md): Pauses a broadcast that is currently sending.
- [Resume a broadcast](https://docs.notifuse.com/api-reference/resume-a-broadcast.md): Resumes a paused broadcast.
- [Cancel a broadcast](https://docs.notifuse.com/api-reference/cancel-a-broadcast.md): Cancels a scheduled broadcast.
- [Send broadcast to individual](https://docs.notifuse.com/api-reference/send-broadcast-to-individual.md): Sends a broadcast to a single recipient for testing purposes. Optionally specify which template variation to send.
- [Delete a broadcast](https://docs.notifuse.com/api-reference/delete-a-broadcast.md): Deletes a broadcast. This action is permanent and cannot be undone.
- [Get A/B test results](https://docs.notifuse.com/api-reference/get-ab-test-results.md): Retrieves the performance metrics for all variations in an A/B test broadcast.
- [Select winning A/B test variation](https://docs.notifuse.com/api-reference/select-winning-ab-test-variation.md): Manually selects the winning variation for an A/B test broadcast. The winning variation will be sent to the remaining audience. This endpoint is restricted in demo mode.
- [List templates](https://docs.notifuse.com/api-reference/list-templates.md): Retrieves a list of all templates in the workspace. Supports optional filtering by category and channel.
- [Get a template](https://docs.notifuse.com/api-reference/get-a-template.md): Retrieves a single template by ID. Optionally specify a version number to retrieve a specific version.
- [Create a template](https://docs.notifuse.com/api-reference/create-a-template.md): Creates a new template. Each template must have a channel (email or web) with corresponding channel-specific content.
- [Update a template](https://docs.notifuse.com/api-reference/update-a-template.md): Updates an existing template. Creates a new version of the template. The email's `editor_mode` must stay the one the template was created with; to switch between the visual editor and MJML code, create a new template. A deleted template cannot be updated.
- [Delete a template](https://docs.notifuse.com/api-reference/delete-a-template.md): Soft-deletes a template: it disappears from `templates.list` and can no longer be updated, but every version is kept, because messages already sent (message history, broadcast reports) are rendered from them. `templates.get` still returns it, with `deleted_at` set. Its id stays reserved: creating a…
- [Compile template](https://docs.notifuse.com/api-reference/compile-template.md): Compiles an MJML template with provided data, returning the rendered HTML. When `subject` and/or `subject_preview` are provided, they are rendered through the same Liquid engine used at send time and returned alongside the HTML so callers do not need to run a separate Liquid pass to preview the subj…
- [List blog categories](https://docs.notifuse.com/api-reference/blog/list-blog-categories.md): Returns every category of the workspace's blog, newest first. Not paginated. Requires the blog read permission.
- [Get a blog category](https://docs.notifuse.com/api-reference/blog/get-a-blog-category.md): Retrieves a category by `id` or by `slug`; when both are given, `id` wins. Requires the blog read permission.
- [Create a blog category](https://docs.notifuse.com/api-reference/blog/create-a-blog-category.md): Creates a category. Posts always belong to one, so a blog needs at least one category before its first post. Requires the blog write permission.
- [Update a blog category](https://docs.notifuse.com/api-reference/blog/update-a-blog-category.md): Replaces a category's name, slug, description and SEO settings. This is not a patch: optional fields left out are cleared. Public pages are cached for up to 5 minutes, so a rename can take that long to show on the blog. Requires the blog write permission.
- [Delete a blog category](https://docs.notifuse.com/api-reference/blog/delete-a-blog-category.md): Deletes a category **and every post in it**, in one transaction. Both are soft-deleted, which frees their slugs for reuse. Public pages are cached for up to 5 minutes, so the category can take that long to disappear from the blog. Requires the blog write permission.
- [List blog posts](https://docs.notifuse.com/api-reference/blog/list-blog-posts.md): Returns posts page by page, drafts included unless filtered out. Posts come newest-created first; with `status=published`, most recently published first. Page through with `page` and `limit` until you have `total_count` posts. Requires the blog read permission.
- [Get a blog post](https://docs.notifuse.com/api-reference/blog/get-a-blog-post.md): Retrieves a post by `id` or by `slug`; when both are given, `id` wins. Drafts are returned too. Requires the blog read permission.
- [Create a blog post](https://docs.notifuse.com/api-reference/blog/create-a-blog-post.md): Creates a post as a draft. The post holds the metadata; its body lives in a web template, so publishing a post over the API takes three calls:
- [Update a blog post](https://docs.notifuse.com/api-reference/blog/update-a-blog-post.md): Replaces a post's metadata. This is not a patch: optional fields left out are cleared, so send the post back with your changes applied.
- [Delete a blog post](https://docs.notifuse.com/api-reference/blog/delete-a-blog-post.md): Soft-deletes a post, which takes it off the blog and frees its slug. Its template is left in place. Requires the blog write permission.
- [Publish a blog post](https://docs.notifuse.com/api-reference/blog/publish-a-blog-post.md): Publishes a draft: it appears on the blog's home and category pages, at its own URL, and in the RSS and JSON feeds. Publishing a post that is already published is refused; unpublish it first to change its date. Requires the blog write permission.
- [Unpublish a blog post](https://docs.notifuse.com/api-reference/blog/unpublish-a-blog-post.md): Turns a published post back into a draft and clears its publication date. Requires the blog write permission.
- [List blog theme versions](https://docs.notifuse.com/api-reference/blog/list-blog-theme-versions.md): Returns the workspace's theme versions, newest first, files included. Requires the blog read permission.
- [Get a blog theme version](https://docs.notifuse.com/api-reference/blog/get-a-blog-theme-version.md): Retrieves one theme version with its files. Requires the blog read permission.
- [Get the published blog theme](https://docs.notifuse.com/api-reference/blog/get-the-published-blog-theme.md): Retrieves the theme version currently live on the blog. Requires the blog read permission.
- [Create a blog theme version](https://docs.notifuse.com/api-reference/blog/create-a-blog-theme-version.md): Saves a new, unpublished theme version, numbered one above the highest existing version. Files left out are stored empty. Nothing changes on the blog until the version is published. Requires the blog write permission.
- [Update a blog theme version](https://docs.notifuse.com/api-reference/blog/update-a-blog-theme-version.md): Edits an unpublished theme version in place. Only the files named in `files` are replaced. The published version cannot be edited: create a new version, or edit an older one, and publish that instead. Requires the blog write permission.
- [Publish a blog theme version](https://docs.notifuse.com/api-reference/blog/publish-a-blog-theme-version.md): Makes a theme version the one the blog renders, and unpublishes the previous one in the same transaction. Any version can be published, so rolling back is publishing an older one. Requires the blog write permission.
- [Create a webhook subscription](https://docs.notifuse.com/api-reference/create-a-webhook-subscription.md): Creates a new webhook subscription to receive HTTP callbacks when specified events occur in the workspace.
- [List webhook subscriptions](https://docs.notifuse.com/api-reference/list-webhook-subscriptions.md): Returns all webhook subscriptions for the specified workspace.
- [Get a webhook subscription](https://docs.notifuse.com/api-reference/get-a-webhook-subscription.md): Retrieves a specific webhook subscription by ID.
- [Update a webhook subscription](https://docs.notifuse.com/api-reference/update-a-webhook-subscription.md): Updates an existing webhook subscription with new configuration.
- [Delete a webhook subscription](https://docs.notifuse.com/api-reference/delete-a-webhook-subscription.md): Permanently deletes a webhook subscription. This action cannot be undone.
- [Toggle webhook subscription enabled state](https://docs.notifuse.com/api-reference/toggle-webhook-subscription-enabled-state.md): Enables or disables a webhook subscription. Disabled subscriptions will not receive events.
- [Regenerate webhook secret](https://docs.notifuse.com/api-reference/regenerate-webhook-secret.md): Generates a new signing secret for the webhook subscription. The old secret will immediately become invalid.
- [Get webhook delivery history](https://docs.notifuse.com/api-reference/get-webhook-delivery-history.md): Returns the delivery history for a webhook subscription, including status and response information.
- [Send a test webhook](https://docs.notifuse.com/api-reference/send-a-test-webhook.md): Sends a test webhook to the subscription's URL to verify connectivity and configuration.
- [List available event types](https://docs.notifuse.com/api-reference/list-available-event-types.md): Returns a list of all available webhook event types that can be subscribed to.
- [List audit logs](https://docs.notifuse.com/api-reference/audit-logs/list-audit-logs.md): Returns one page of audit entries, newest first. With scope=workspace (the default) workspace_id is required and the caller must be an owner of that workspace or hold the audit_logs read permission; with scope=deployment the caller must be a root user and every entry is returned, optionally narrowed…
- [Get an audit log entry](https://docs.notifuse.com/api-reference/audit-logs/get-an-audit-log-entry.md): Returns one entry by id. In workspace scope an entry of another workspace is a 404, never a leak.
- [List audit actions](https://docs.notifuse.com/api-reference/audit-logs/list-audit-actions.md): The catalogue of every action the log can contain, sorted by name, with its category. The console builds its action filter from it.
- [Export audit logs](https://docs.notifuse.com/api-reference/audit-logs/export-audit-logs.md): Streams the entries the filter selects, newest first, as a CSV or NDJSON file download, up to 100 000 rows. When the cap is reached the response ends with an export.truncated marker row; narrow the date range for the rest. The same authorisation as auditLogs.list applies, before the first byte is wr…
- [Set the workspace audit log retention](https://docs.notifuse.com/api-reference/audit-logs/set-the-workspace-audit-log-retention.md): Owners only. retention_days absent means the deployment default; 0 keeps every entry forever; otherwise 30 to 3650. Works in every licence state.

## OpenAPI Specs

- [openapi](/openapi.json)

## Optional

- [Cloud](https://cloud.notifuse.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.