Skip to main content
This walkthrough drafts a newsletter, targets an audience, sends a test, sends or schedules the campaign, and shows the follow-up pattern for people who did not open it. It uses the Newsletter and Contact resources. Who is this for: marketing-automation pipelines that compose campaigns from a CRM, and admin tools that schedule sends ahead of time. Your token needs communication rights over the audience: organization-wide communication rights, or newsletter reach over the chapter you target.

Step 1: Draft the newsletter

A newsletter has content, a subject, and exactly one audience. The content is sent from htmlInline (the fully inlined HTML). The visual builder also stores its editable source in design and a raw copy in htmlRaw; an integration that supplies HTML only needs htmlInline.
The response carries id, uuid and status: "Draft". Newsletter statuses are capitalized: Draft, Scheduled, Sending, Sent, Stop, Failed. Addresses use the uuid: /api/v1/newsletters/{uuid}.

Choosing the audience

Set one of these targeting fields. If several are set, Orgo uses the first that applies, in this order: a follow-up’s parent newsletter, isGeneral, unit, isContacts, event, sendToEverybody, userList. localCenter caps the audience to one chapter, and includeSubCenters: true adds the chapters under it. Unless you set isInformational: true, only people who are subscribed to newsletters receive it. recipients shows how many people the audience resolves to.

Placeholders

{{firstName}}, {{lastName}}, {{email}} and the organization’s custom fields are replaced per recipient at send time. The forms {x}, {{x}} and {{ x }} all work. An unsubscribe link and a preferences link are appended automatically unless your content has {unsubscribeUrl}; a public newsletter also gets a “view in browser” link.

Step 2: Send a test

Always test first. Send the newsletter to yourself with the preview flag:
The test goes to the email address of the token’s user, with placeholders filled from that user’s profile. It does not count in the campaign’s statistics, and the unsubscribe link in it is inert. Check placeholders, links, images and the footer. An empty newsletter answers 400 Newsletter content is empty. (POST /api/v1/email_templates/send-test is for email templates, not newsletters.)

Step 3: Send now or schedule

Send immediately

The status moves to Sending and then Sent as the queue drains. A large campaign takes a few minutes. A newsletter without a valid audience or content answers 400 Newsletter must have a valid target and content, and one that is already sending or sent answers 400 Newsletter has already been sent.

Schedule for later

Send the same call with scheduledAt:
scheduledAt is in UTC, at least 2 minutes ahead, and must fall on a quarter hour (:00, :15, :30, :45). timezone records the zone it was picked in (default: the organization’s) and does not shift the time. The status becomes Scheduled. An unparseable time answers 400. To move a scheduled send, PATCH .../schedule with a new scheduledAt. Sending {"scheduledAt": null} there cancels the schedule and returns the newsletter to Draft. To stop a campaign that is already going out, PATCH .../stop.

Step 4: Follow up with non-openers

A common pattern: wait a few days, then re-send to people who did not open the first email.
The clone is a Draft named Follow-up: <original name> with the same content. Its audience is fixed to the non-openers of the original (shown in parentNewsletter and recipients); you cannot widen it. It only works on a newsletter that is Sent, and answers 400 when everyone opened it or the remaining recipients bounced or unsubscribed. Give the follow-up its own subject, then send it as in step 3:

Step 5: Read engagement statistics

Once the send runs, opens and clicks accumulate. Read them from the newsletter:
Besides the fields above, the response carries counts named rateSent, rateOpen, rateClick, rateBounced, rateCompliant (spam complaints) and rateUnsubscribe, plus clicks, the per-link click statistics. Despite the rate prefix, they are counts of unique recipients, not percentages. These statistics fields are not in the OpenAPI schema. For recipient-level data, GET /api/v1/newsletters/{uuid}/stats-export returns {"url": ...}, a download link (valid 15 minutes) to a CSV with one row per recipient and a “Yes” under each action recorded (Delivered, Opened, Clicked, Bounced, Complained, Unsubscribed, Rejected, Failed).

Common gotchas

Three filters apply: the audience field you chose, the localCenter cap (and includeSubCenters), and the recipient’s newsletter subscription. Unsubscribed people are skipped unless the newsletter is isInformational. The newsletter’s recipients field shows the resolved count before you send.
Check the spelling against the organization’s merge fields; a name that matches no field is left as typed. If a recipient’s value is empty the placeholder resolves to nothing, so avoid leaving dangling punctuation around it.
Sending goes through a managed queue and a large audience takes minutes. Read the newsletter again: the status moves to Sent when the queue drains. If sends from your organization are failing, check Settings → Developers → Logs and contact support.
Not directly. The pattern is to send variant A to a smaller list or unit, compare open counts, then send the winner to the rest.

What to do next