Skip to main content
Creates a mailing list in the current project. A list is the audience for a release notes email: send_release_email delivers a completed generate_release_notes_email draft to one or more lists, deduplicating recipients across them and giving every email a one-click unsubscribe link. A project holds at most 20 lists and names are unique per project — a repeat call with the same name fails rather than duplicating. The new list is empty; fill it with upsert_mailing_list_recipients, the dashboard’s CSV import under Destinations → Email, or the REST sync recipes from your own user database. Creating lists and managing recipients never costs credits; only generation does.

Arguments

Returns

Keep the id: it is what send_release_email and the recipient tools take. The three counts track a recipient’s status over the life of the list:
  • active_recipients receive the next email. A list holds up to its plan’s cap of active recipients (500 on Free, 2,500 on Solo, 10,000 on Team); an upsert that would cross the cap is rejected whole.
  • removed_recipients were taken off by your team (the dashboard’s trash or remove_mailing_list_recipients). Soft and reversible — a later upsert or the dashboard’s Restore puts them back.
  • unsubscribed_recipients opted out themselves via the link in an email. Terminal: an upsert reports them as skipped_unsubscribed and they are never re-added, so re-importing a CSV cannot resurrect an opt-out.

Errors

  • A project can have at most 20 mailing lists — delete or reuse an existing list.
  • A list with this name already exists — pick another name, or look the existing one up with list_mailing_lists.
  • The name is blank or longer than 100 characters.

Example prompts

“Create a mailing list called Design partners and add these five people to it.”
“Set up a Beta testers list, then send the release email for the latest draft to it.”
“We want a separate list for enterprise customers — create it and import the CSV I’m pasting.”