Send a newsletter campaign - Orgo Documentation

This walkthrough drafts a newsletter, targets a specific audience, sends it, and demonstrates a follow-up pattern (re-sending to people who didn’t open). It uses the Newsletter and Contact resources. Who is this for: marketing-automation pipelines that compose campaigns from a CRM, A/B testers running variations, or admin tools that schedule sends ahead of time.

Newsletters are owned by a Unit — usually a local center or the tenant root. The audience is implicitly everyone in that unit who has newsletter opt-in.

curl -X POST https://acme.orgo.space/api/v1/newsletters \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "January 2026 — Boston Update",
    "subject": "What'\''s happening at Civic Collective in January",
    "fromName": "Civic Collective — Boston",
    "fromEmail": "boston@example.com",
    "replyToEmail": "boston@example.com",
    "unit": "/api/v1/units/4",
    "content": "<h1>January Update</h1><p>Hello {{firstName}},</p><p>Here'\''s what'\''s coming up...</p>"
  }'

Response:

{
  "id": 44,
  "uuid": "01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44",
  "name": "January 2026 — Boston Update",
  "status": "DRAFT",
  "estimatedRecipientCount": 312
}

estimatedRecipientCount is the count of recipients the current audience filter would target right now. It is recalculated each time you fetch the newsletter.

Placeholders

{{firstName}}, {{lastName}}, {{email}} and any tenant custom field are resolved per recipient. Use them anywhere in content and they’re substituted at send time.

Step 2 — Preview and test-send

Always send a test to yourself first.

curl -X POST https://acme.orgo.space/api/v1/email_templates/send-test \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newsletter": "/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44",
    "toEmail": "james.patterson@example.com"
  }'

Check the test email rendered correctly — placeholder substitution, links, images, and unsubscribe footer.

Step 3 — Choose: schedule or send now

Send immediately

curl -X PATCH https://acme.orgo.space/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44/send \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{}'

Status flips to SENT. The actual delivery is queued — large campaigns take a few minutes to flush through SES.

Schedule for later

curl -X PATCH https://acme.orgo.space/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44/schedule \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"sendDate": "2026-01-20T09:00:00-05:00"}'

Status flips to SCHEDULED and the worker picks it up at the specified time.

Step 4 — Resend to non-openers (one week later)

A standard pattern: wait 5-7 days after the initial send, then re-send (with a new subject line) only to people who haven’t opened. First check how many would be re-targeted:

curl https://acme.orgo.space/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44/non-openers-count \
  -H "Api-Token: $ORGO_API_TOKEN"

Then clone the original into a new draft targeting only those non-openers:

curl -X POST https://acme.orgo.space/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44/clone-non-openers \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Reminder — what'\''s happening at Civic Collective in January"
  }'

The clone keeps the body content but you can edit before sending. Then PATCH /api/v1/newsletters/{uuid}/send as usual.

Step 5 — Read engagement statistics

Once the send completes (typically a few minutes after triggering), opens and clicks start streaming in. Fetch them on the newsletter resource:

curl https://acme.orgo.space/api/v1/newsletters/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f44 \
  -H "Api-Token: $ORGO_API_TOKEN"

The response includes recipientCount, openCount, clickCount, and unsubscribeCount.

Common gotchas

Placeholders showed up as `{{firstName}}` instead of names

Placeholders are case-sensitive and must match exactly. {{FirstName}} won’t work; neither will {{ firstName }} (with spaces). If a recipient’s field is null, the placeholder resolves to an empty string — consider wrapping with HTML so empty fields don’t leave dangling punctuation.

The send is stuck at SENT but nobody got the email

SES has per-tenant sending limits. New tenants are sandboxed (50 emails/day, verified-recipient only) until granted production access. Check Settings → Developers → Email for the current quota. Contact support to lift sandbox.

Can I A/B test subject lines?

Not directly — there’s no first-class A/B testing UI. The pattern is: send the campaign to a 10% sample (filter the audience tighter), wait, compare open rates against a held-back variant, then send the winner to the rest.

What to do next

Sync your CRM with Orgo — keep contacts subscribed in sync with your CRM source-of-truth
Handle webhooks — react to contact.updated when someone unsubscribes
Rate limits — newsletter sends carry email-cost rate limits

​Step 1 — Draft the newsletter

​Placeholders

​Step 2 — Preview and test-send

​Step 3 — Choose: schedule or send now

​Send immediately

​Schedule for later

​Step 4 — Resend to non-openers (one week later)

​Step 5 — Read engagement statistics

​Common gotchas

​What to do next

Step 1 — Draft the newsletter