API · Event communications

Event communications send practical information to buyers with valid tickets, including arrival details and requests to complete missing information. These endpoints use the same Messages tab and Open answers worklist as the admin.

Read requests require a read or write token. Every mutation requires a write token. Personal co-organizer tokens are limited to assigned events. Message IDs and delivery IDs are opaque public IDs. Communication is available by default on non-cancelled accounts. Platform staff may block an account for misuse; its communication endpoints then return 403, and pending delivery stops.

Draft and review

Method	Path	Purpose
`GET`	`/admin/events/:slug/communications`	List messages, newest first.
`POST`	`/admin/events/:slug/communications`	Create an unsent draft.
`GET`	`/admin/events/:slug/communications/:id`	Read content, preview, and delivery counts.
`PATCH`	`/admin/events/:slug/communications/:id`	Edit a draft. Confirmed content is frozen.
`DELETE`	`/admin/events/:slug/communications/:id`	Permanently delete an unsent message.

Create and update use the event_communication object:

{
  "event_communication": {
    "subject": "Please complete your information for Spring Showcase",
    "body": "Please open your booking below and complete the outstanding details before the deadline. Thank you!",
    "audience": "missing_answers",
    "schedule": "before_event",
    "hours_before": 48
  }
}

Field	Meaning
`subject`	Required plain text, up to 200 characters, no line breaks.
`body`	Required plain text, up to 10,000 characters.
`audience`	`all_buyers` (default), `ticket_type`, or `missing_answers`.
`ticket_id`	Required for `ticket_type`; must belong to this event.
`schedule`	`now` (default), `at_time`, or `before_event`. All require a separate confirmation.
`scheduled_at`	Required for `at_time`. Prefer ISO 8601 with an offset; input without an offset uses the event timezone.
`hours_before`	For `before_event`: integer 1–720, default 24.

Create returns 201 Created with Location. Update and show return 200 OK. Example draft response:

{
  "id": "message-public-id",
  "event_slug": "spring-showcase",
  "subject": "Please complete your information for Spring Showcase",
  "body": "Please open your booking below and complete the outstanding details before the deadline. Thank you!",
  "audience": "missing_answers",
  "ticket_id": null,
  "schedule": "before_event",
  "scheduled_at": "2032-05-18T17:00:00Z",
  "hours_before": 48,
  "timezone": "Europe/Berlin",
  "status": "draft",
  "deletable": true,
  "confirmed_at": null,
  "completed_at": null,
  "delivery_counts": {},
  "delivery_policy": {
    "interval_seconds": 2,
    "daily_limit": 300,
    "recipient_limit": null
  },
  "billing": {
    "price_per_email": { "amount": "0.01", "currency": "EUR" },
    "estimated_cost": { "amount": "0.18", "currency": "EUR" },
    "retry_cost": { "amount": "0.00", "currency": "EUR" },
    "reserved": { "amount": "0.00", "currency": "EUR" },
    "spent": { "amount": "0.00", "currency": "EUR" },
    "available_credit": { "amount": "10.00", "currency": "EUR" }
  },
  "preview_id": "exact-preview-fingerprint",
  "recipient_count": 18,
  "recipient_sample": [
    { "email": "buyer@example.com", "name": "Sam Buyer", "booking_count": 2 }
  ],
  "deliveries_url": "https://app.usetix.io/admin/events/spring-showcase/communications/message-public-id/deliveries.json"
}

recipient_sample contains at most 25 addresses. Preview fields are present only while the message is a draft. Neither previews nor test mail expose personal buyer booking links. Real buyer emails include those links automatically.

Listing returns communications (each with id, subject, status, created_at) and next_page. Pass the returned next_page as the page query parameter until it is null. Pages contain up to 25 messages.

Confirm, test, stop, and retry

Method	Path suffix after `/communications/:id`	Body
`POST`	`/confirmation`	`{ "preview_id": "exact-preview-fingerprint" }`
`POST`	`/test_delivery`	No parameters. Sends only to the acting organizer.
`POST`	`/cancellation`	No parameters. Stops pending work.
`POST`	`/retry`	No parameters. Retries known failed deliveries of a completed message.

These endpoints return the message with 200 OK. Present the complete draft, audience, recipient count, timing, price and total credit cost to the organizer before confirming. A changed draft, price or recipient selection invalidates its preview. Confirmation is idempotent; repeating it does not create another send. Past delivery times and empty audiences cannot be confirmed.

Each address receives one email combining its eligible bookings. Recipients, including scheduled audiences, are fixed when the organizer confirms the credit cost. Later buyers require a new message. The worker rechecks that the snapshotted bookings still qualify. Cancelled, refunded, archived, or released bookings and cancelled admissions are excluded, as are guest-list parties. Missing-answer messages exclude bookings whose remaining answers can no longer be edited.

Relative reminders follow changes to the event start before dispatch. They are skipped after the event starts. These are one-time messages; they do not repeatedly send to buyers who purchase after confirmation. Scheduled work normally starts within the scheduler’s one-minute interval, subject to queue availability.

The approving organizer must retain event access at dispatch and delivery, and the account must remain active. Test mail contains no buyer secrets, records no customer outreach, and uses the same shared sending budget as buyer mail. A submitted recipient address does not override the acting organizer’s mailbox.

Credit costs

Event messages use Usetix Credits, with an initial price of 0.01 per recipient and message in the account currency (EUR, USD, GBP, CHF or CAD). This is the final gross credit deduction; no additional VAT is added to that deduction. Always display the returned price and amount: platform staff can change the price centrally, and confirmed messages retain their original price.

billing is included in draft, show and mutation responses:

Field	Meaning
`price_per_email`	Current draft price, or the price fixed at confirmation.
`estimated_cost`	Draft recipient count × price. `null` after confirmation.
`retry_cost`	Current failed count × the original price. Show before approving a retry.
`reserved`	Credit currently reserved for unfinished deliveries.
`spent`	Credit charged for accepted deliveries of this message.
`available_credit`	Account credit available after all existing reservations.

Money fields use { "amount": "0.18", "currency": "EUR" }. Confirmation reserves the full cost and fixes the recipient list atomically. Insufficient credit returns 409, leaving the draft unchanged. Fund the existing Usetix credit account before confirming again. Automatic top-up follows existing account settings; it does not bypass the sufficient-credit check.

Only an email accepted by the mail server is charged. Failed, skipped, stopped, and unknown deliveries release their reservations without charge. A confirmed retry reserves the failed recipients again at the original price. Each accepted delivery can produce at most one charge, even if a job is repeated. Test emails, ticket emails, receipts and login emails remain included and never debit credits.

The credit dashboard includes a separate email usage breakdown. Monthly platform invoices list email charges as already paid; they do not collect them again. Messages confirmed before credit billing retain their original free terms.

Sending capacity

delivery_policy reports the current platform settings: minimum seconds between send attempts, attempts per rolling 24 hours, and an optional per-message recipient limit (null means no per-message limit). The example above shows the initial defaults. Platform staff edit these centrally under Platform → Email delivery; organizer tokens cannot change global settings. Test mail and failed attempts consume the same budget. A busy budget defers buyer messages automatically.

Messages use a dedicated worker queue and reserve capacity across all accounts. Changes to sending settings reconsider waiting deliveries within a minute, while preserving already consumed attempts. If a recipient limit is configured, it is checked at confirmation and again before dispatch; reducing the limit can stop a confirmed message before sending. The account and approving organizer must retain access when delivery resumes.

Delete an unsent message

DELETE /admin/events/:slug/communications/:id permanently removes a message and its recipient records. It returns 204 No Content; subsequent reads return 404. The message response exposes deletable so clients can display this action.

Drafts, cancelled messages and completed failures can be deleted if there are no ongoing (sending), accepted (sent) or uncertain (unknown) deliveries, and no consumed credit. Stop a scheduled or sending message first. Test emails do not prevent deletion. An incompatible current state returns 409 with an error under base; permissions are unchanged and a write token is required.

Deletion atomically releases any remaining credit reservations and removes the uncharged reservation records. Already queued jobs for the deleted message are discarded without sending. Accepted or uncertain delivery history is retained.

Delivery status

GET /admin/events/:slug/communications/:id/deliveries returns:

{
  "deliveries": [
    {
      "id": "delivery-public-id",
      "email": "buyer@example.com",
      "name": "Sam Buyer",
      "status": "sent",
      "sent_at": "2032-05-18T17:00:20Z",
      "available_at": null
    }
  ],
  "total_count": 18,
  "next_page": null
}

Pages contain up to 25 deliveries. Use next_page as the next page value.

Message statuses are draft, scheduled, sending, completed, and cancelled. completed means processing finished, including any failed, skipped, or unknown results. delivery_counts groups counts by delivery status:

Delivery status	Meaning
`pending`	Waiting for a worker or sending budget. `available_at` is the earliest retry time when deferred.
`sending`	A worker has claimed the email.
`sent`	Accepted by the mail server; not proof of inbox delivery.
`failed`	Known connection or authentication failure before sending; eligible for explicit retry.
`unknown`	Acceptance is uncertain, including interrupted delivery. Never retried through this feature.
`skipped`	Stopped, no longer eligible, expired reminder, or organizer access revoked.

Stopping affects pending work; messages already being sent may complete. An unknown result must be investigated before taking any further action, since resending could duplicate an email that was accepted. Successful messages create email_sent entries in the customer interaction history.

SMTP errors without a known protocol phase remain unknown, since an error can occur during session teardown after acceptance. Explicit retries retain the retrying organizer’s current event access.

Validation failures return 422 with { "errors": { "field": ["message"] } }. Stale previews, insufficient credit and invalid lifecycle actions return 409 with errors under base. A test email also returns 409 when the shared sending budget is unavailable.

Assistant, MCP, and CLI

ManageEventCommunicationsTool exposes list, show, create, update, confirm, test, cancel, retry, delete, and deliveries. Sending, testing, retrying and permanent deletion require explicit organizer approval via confirmed: true; confirm also requires preview_id. Draft creation supports information and missing_answers templates. Scheduled audiences and permissions are the same as in the admin and API.

The CLI’s existing API command can access every endpoint:

usetix api GET /admin/events/spring-showcase/communications
usetix api GET /admin/events/spring-showcase/communications/message-public-id/deliveries