# Newsletter

URL: /business/nouns/newsletter · Id: `noun:newsletter`

> A Newsletter is a list of Contacts who subscribed to a Startup’s issues by email, with the Offer that gates its paid issues.

A Newsletter is a list of [Contacts](/business/nouns/contact) who subscribed to a [Startup](/business/nouns/startup)’s issues by email, with the [Offer](/business/nouns/offer) that gates its paid issues.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | What subscribers see it called. |
| `from` | [Mailbox](/business/nouns/mailbox) | Yes | The broadcast Mailbox each issue sends from. |
| `topic` | `string` | No | The topic a Contact subscribes to, recorded with their Consent. |
| `subscribers` | `integer` | No | Contacts subscribed now, counted from their Consent. |
| `offer` | [Offer](/business/nouns/offer) | No | The Offer whose Subscription unlocks paid issues and the archive. |

## Object
```json
{
  "$id": "https://api.sb/leaseline.app/newsletters/newsletter_FLjN3aQujc",
  "$type": "Newsletter",
  "name": "Leaseline notes",
  "from": "mailbox_93HvOnR17L",
  "topic": "product-updates",
  "subscribers": 1,
  "offer": "offer_2hzYe1ERo0"
}
```

## Relationships
- <a id="rel-sends-from"></a>A Newsletter **sends from** one [Mailbox](/business/nouns/mailbox): every issue sends from one broadcast [Mailbox](/business/nouns/mailbox). `sendsFrom`, inverse [`newsletters`](/business/nouns/mailbox#rel-newsletters).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Newsletter.import](/business/nouns/newsletter/import) | Import adds subscribers from a CSV File, keeping each one’s consent basis and the date they subscribed. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Newsletter.imported`](/business/events/Newsletter.imported) | Two-way: `try`, `send`, `do` |
| [Newsletter.send](/business/nouns/newsletter/send) | Send emails one issue, a piece of Content, to every subscribed Contact, and a paid issue only to those whose Offer covers it. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Newsletter.sent`](/business/events/Newsletter.sent) | One-way: `send`, `do` |
| <a id="create"></a>[Newsletter.create](/business/nouns/newsletter/create) | Creates a Newsletter. Inherited from [Noun](/business/nouns/noun). | None. | `Newsletter.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Newsletter.get](/business/nouns/newsletter/get) | Returns one Newsletter by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Newsletter.list](/business/nouns/newsletter/list) | Returns Newsletters, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Newsletter.update](/business/nouns/newsletter/update) | Changes the given properties of a Newsletter. Inherited from [Noun](/business/nouns/noun). | None. | `Newsletter.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Newsletter.delete](/business/nouns/newsletter/delete) | Deletes a Newsletter: a soft delete that keeps its history, undone by `Thing.restore`. Inherited from [Noun](/business/nouns/noun). | None. | `Newsletter.deleted` | Two-way: `try`, `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Newsletter.create` | Yes | Yes | Yes | No |
| `Newsletter.get` | Yes | Yes | Yes | Yes |
| `Newsletter.list` | Yes | Yes | Yes | Yes |
| `Newsletter.update` | Yes | Yes | Yes | No |
| `Newsletter.delete` | Yes | Yes | Yes | No |
| `Newsletter.import` | Yes | Yes | Yes | No |
| `Newsletter.send` | Yes | No | No | No |

## Call it
In code: [API](/code/api/newsletter) · [SDK](/code/sdk/newsletter) · [CLI](/code/cli/newsletter) · [MCP](/code/mcp/newsletter).

**Ask**

```text
Send the latest newsletter with content.
```

**API**

```bash
curl -X POST https://api.sb/leaseline.app/newsletters/newsletter_FLjN3aQujc/send \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"content_HYlnoorBdP"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "newsletter": {
    "$id": "https://api.sb/leaseline.app/newsletters/newsletter_FLjN3aQujc",
    "$type": "Newsletter",
    "name": "Leaseline notes",
    "from": "mailbox_93HvOnR17L"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Newsletter.send",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const newsletter = await $.Newsletter.send({ newsletter: 'newsletter_FLjN3aQujc', content: 'content_HYlnoorBdP' })
```

**CLI**

```bash
npx startup-builder do Newsletter.send --json '{"newsletter":"newsletter_FLjN3aQujc","content":"content_HYlnoorBdP"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Newsletter.send({ newsletter: 'newsletter_FLjN3aQujc', content: 'content_HYlnoorBdP' })"
  }
}
```

## Works with
| With | Links |
| --- | --- |
| Roles | [Marketing Lead](/agents/marketing/marketing-lead) |
| Systems | [Email list](/systems/email-list) |
| Guides | [Start a newsletter](/systems/marketing/start-a-newsletter) |

## Example
Leaseline’s Newsletter on lease law sends from its broadcast [Mailbox](/business/nouns/mailbox) to 900 subscribers. The monthly issue goes to all of them; the weekly issue goes only to subscribers whose [Subscription](/business/nouns/subscription) to the $8 Offer covers it.