Notify

Notify sends mailings to the contacts of your customers. The API does what the screens do, through the same actions and the same rules.

Scopes and who may do what#

Three scopes, each a bigger step than the last:

A scope only narrows what the token's owner may do. On top of it:

• A guest (a client) gets 403 everywhere, and so does a workspace that has switched Notify off.
• A member may read, draft and send test mails to themselves or a colleague.
• Only a workspace administrator may send or schedule, and send a test mail to any address.

The MCP server offers the read and draft tools (polder_list_mailings, polder_create_mailing_draft, …) but never sending: an assistant prepares a draft and a person sends it. See Scopes.

A mailing#

A mailing is a draft until somebody sends it.

List categories#

The workspace's mail categories. A mailing needs one; an unsubscribable category is one that recipients can opt out of.

curl https://backlog.polder.work/api/v1/workspaces/7/notify/categories \
  -H "Authorization: Bearer $POLDER_TOKEN"

{ "data": [{ "id": 2, "name": "Product news", "unsubscribable": true }] }

List contacts#

The contacts of the workspace's customers, ordered by name and paged.

{
  "data": [{
    "id": 31, "name": "Sanne de Vries", "email": "sanne@example.com", "language": "nl", "role": "Owner",
    "status": "…", "customer": { "id": 4, "name": "Acme" }
  }],
  "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

List segments#

All segments of the workspace, ordered by name. kind and filters describe how the segment picks its customers; a segment that lists customers or contacts by hand also has customer_ids or contact_ids.

{ "data": [{ "id": 5, "name": "Dutch customers", "kind": "…", "filters": {} }] }

Preview a segment's audience#

Who one segment reaches for a category right now: the counts and why people fall away, plus a sample. The addresses of everybody are never listed.

A segment of another workspace is a 404.

{
  "data": {
    "customers": 12, "contacts": 40, "reachableContacts": 38, "reachableCustomers": 12,
    "dropped": { "unsubscribed": 1, "suppressed": 1, "expired": 0, "customersWithoutAddress": 0 },
    "sample": [{ "id": 31, "name": "Sanne de Vries", "email": "sanne@example.com", "customer": "Acme", "blocked": null }]
  }
}

sample holds at most 50 contacts; blocked says why a contact is dropped, or is null.

List mailings#

Mailings, newest first, paged. Filter with ?status= (one of the statuses above), page with page and per_page. The body is left out of the list.

{
  "data": [{ "id": 12, "subject": "Maintenance on Friday", "status": "draft", "…": "…" }],
  "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

Get a mailing#

One mailing with its body and stats. A mailing from another workspace is a 404.

stats counts recipients: sent, pending, failed, cancelled, delivered, bouncedHard, bouncedSoft, complaints, unsubscribed, replies, and for tracking opened, clicked, clicks and botEvents.

Note opened is an upper bound. Mail clients that preload images and link scanners show up as opens; those are counted separately as botEvents where Polder recognises them.

{
  "data": {
    "id": 12, "subject": "Maintenance on Friday", "status": "sent", "recipients_total": 38,
    "body": "<p>Hello {{naam}},</p>…",
    "stats": { "sent": 38, "delivered": 37, "bouncedHard": 1, "opened": 21, "clicked": 4, "…": "…" }
  }
}

Create a draft#

Creates a mailing in status draft. Every field is optional, so you can start empty and fill it in later. Sending checks that subject, text, category and at least one included segment are present. The mailing starts with the workspace's default for track, and replies go to the team of the workspace's catch-all mailbox until you set reply_team_id. Answers 201 with the mailing, body included.

Body

curl https://backlog.polder.work/api/v1/workspaces/7/notify/mailings \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Maintenance on Friday", "body": "<p>Hello {{naam}},</p>", "mail_category_id": 2, "include_segment_ids": [5]}'

Update a draft#

Changes the fields you send, with the same fields and rules as creating. Only a draft or a scheduled mailing can change; anything else answers 409.

Really changing a scheduled mailing takes it back to draft, so what goes out is always what somebody confirmed. The response then has unscheduled: true. Saving the same values again keeps the schedule.

{ "data": { "id": 12, "status": "draft", "…": "…", "unscheduled": true } }

Send a test mail#

Sends the mailing to one address, exactly as recipients get it, with [Test] in front of the subject. It never touches the recipient list. The address must be yourself or a member of the workspace; an administrator may use any address.

Besides the route's limit, each person gets at most 5 test mails a minute (NOTIFY_TESTS_PER_MINUTE).

{ "data": { "ok": true, "error": null } }

If the mail provider refuses the message the call still answers 200 with ok: false and the provider's error.

Send a mailing#

Sends a draft (or a scheduled mailing) now. Polder checks everything again at this moment, freezes the audience, writes a line in the contact log of every customer reached, and hands the mailing to the queue. The answer is 202 with the mailing in status sending; follow its progress with Get a mailing.

Confirm the recipient count#

Sending cannot be undone, so you must say how many people you expect to mail, the way the screen shows the number.

If the audience is not count any more (somebody unsubscribed, a segment changed) nothing is sent and the response tells you the real number. You can use that to find out the count: send 0 and read context.count from the audience_changed answer. For several segments or an exclusion list that is the only way to see the number for the whole mailing; the segment audience endpoint counts one segment at a time.

curl https://backlog.polder.work/api/v1/workspaces/7/notify/mailings/12/send \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 118, "typed": 118}'

{ "message": "audience_changed", "reason": "audience_changed", "context": { "count": 117 } }

Errors#

Refusals have the shape above, with a stable reason and context holding what you need to try again.

Validation errors on count and typed are the usual 422 with errors.

Schedule a mailing#

Sets a draft (or an already scheduled mailing) to go out at at. It asks for the same confirmation as sending, with count and typed, plus:

Answers 200 with the mailing in status scheduled. The count you confirmed is an indication: the audience is worked out again at the moment of sending, as the person who scheduled it, and it is not sent if they may no longer send. Changing a scheduled mailing takes it back to draft. The errors are those of sending, plus 422 invalid_time when at is too soon or too far ahead.

curl https://backlog.polder.work/api/v1/workspaces/7/notify/mailings/12/schedule \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 38, "at": "2026-11-02T09:00:00+01:00"}'