---
title: "Introduction to Mailer"
slug: "introduction-to-mailer"
updated: 2026-10-05T16:59:55Z
published: 2026-10-05T16:59:55Z
canonical: "developer.rocket.chat/introduction-to-mailer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Mailer

The Mailer API sends a mass email from the workspace to users — the programmatic counterpart of the admin **Mailer** tool used for announcements — and handles the unsubscribe links those emails contain.

## Common workflows

**Send an announcement to workspace users**

1. [Send the mailer email](https://developer.rocket.chat/apidocs/send-mailer-endpoint) with a from address, subject, body, and a query selecting the recipient users.
2. Include the unsubscribe placeholder in the body; recipients who opt out are recorded through the [mailer unsubscribe endpoint](https://developer.rocket.chat/apidocs/mailer-unsubscribe-endpoint) and skipped in future sends.

## Conventions

- Sending requires the `send-mail` admin permission, and the workspace's SMTP settings must be configured for any email to go out.
- The recipient `query` is a MongoDB-style selector over user documents, sent as a JSON string.
- For the admin UI equivalent, see the [Mailer](https://docs.rocket.chat/docs/mailer) user guide.