Signups

Email participants of a signup, by Message Scope

SENDS REAL EMAIL TO REAL PEOPLE, immediately and irreversibly. Requires the messages:send scope, which exists only for this — reminders:send does not grant it, and neither does anything else. Recipients are resolved SERVER-SIDE from scope (+ scopeId): the request carries no address list and no participant ids, and any unrecognized field is rejected with 422 rather than ignored. One email per person, deduplicated by address, so somebody holding three items hears from you once. Metered per organization per UTC day in RECIPIENTS, not in calls, with a ceiling of 1000. A send that would cross it is refused whole (429 daily_ceiling_exceeded) and nothing is delivered — it is never trimmed to fit. Every send writes an audit-log entry (signup.messaged) naming the credential, the scope, the recipient count and the subject; read it back at GET /v1/audit_log. Preview a scope before committing to it by reading /signups/{id}/slot_coverage and /signups/{id}/participants; this endpoint has no dry-run mode. The account that owns the credential must have a verified email address (returns 403 otherwise).

post/signups/{id}/messages

Request

  • Base URL: https://thesignup.app/api/v1
  • URL: https://thesignup.app/api/v1/signups/{id}/messages
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Request body

scope'all' | 'day' | 'shift' | 'person' | 'roster' | 'gaps' required

WHO to message, resolved server-side against the signup's roster. all everyone attending; day one date; shift one Occurrence of a repeating slot; person one participant; roster everyone who has ever held one repeating Shift, across every date it runs; gaps the same people, worded as an ask to cover a short date.

scopeIdstring

What the scope names, when it names something: an event_days row id for day, a time_slots row id (one Occurrence) for shift, a participant registration id for person, <seriesId>#<shiftIndex> for roster and gaps (read both off slot_coverage). Omitted for all, which names itself.

subjectstring required
bodystring required

Plain text. {name}, {slot} and {item} are interpolated per recipient with that person's own name, shift and item; a token with nothing behind it renders the bare noun (time slot, item) rather than an empty string.

Example request

{
  "scope": "roster",
  "scopeId": "8f1c0f9e-0000-4000-8000-000000000001#0",
  "subject": "Saturday setup — one more pair of hands"
}

Response

Send summary. sent + failed equals recipients.

recipientsinteger required

People the scope resolved to, after per-person deduplication. Equals sent + failed.

sentinteger required
failedinteger required

Recipients the mail transport refused. Their addresses are not returned.

Changes

No recorded changes to this operation across all 1 revision of this API.