Campaigns

Create a campaign

Create a campaign in DRAFT. Creating never sends — POST /api/v1/campaigns/{id}/send is the only operation that puts mail on the wire — so a campaign can be built up and reviewed before it costs anything.

The from address is checked against this project's verified domains before the campaign is written, so a campaign never exists with a sender it cannot use.

segment_id is required when audience_type is SEGMENT; audience_condition is required when it is FILTERED. Both answer 422 when missing.

audience_condition is checked when the campaign is written: a filter on a field contacts cannot be filtered on, or an operator that field does not have, answers 400 naming it. A list is not a filter field — to mail a list, send audience_type: "LIST" with a top-level list_id.

Requires the campaigns:write scope — Create, edit, and organize your campaigns.

post/api/v1/campaigns

Request

  • Base URL: https://api.sendly.now
  • URL: https://api.sendly.now/api/v1/campaigns
  • Auth: one of:
    • HTTP bearer
    • API key in cookie better-auth.session_token
    • OAuth 2 (authorization code, authorization URL https://app.sendly.now/api/auth/oauth2/authorize, token URL https://app.sendly.now/api/auth/oauth2/token, scopes: campaigns:write)

Headers

Idempotency-Keystring

Replay-safety key (24h TTL). Reuse it only to retry the identical request.

Request body

audience_type'ALL' | 'FILTERED' | 'SEGMENT' | 'LIST' required

ALL — every subscribed contact. FILTERED — the contacts matching audience_condition. SEGMENT — the members of segment_id. LIST — the CONFIRMED members of list_id, which is the only audience that honours double opt-in: a member who never confirmed, or who unsubscribed, is not mailed.

bodystring required
descriptionstring
email_category'TRANSACTIONAL' | 'MARKETING' | 'SELF_MANAGED_UNSUBSCRIBE'
fromstring email required

Sender address. Its domain must be verified for this project.

from_namestring nullable
list_idstring uuid

Required when audience_type is LIST. Only that list's CONFIRMED members receive the campaign.

namestring required
reply_tostring email nullable
segment_idstring uuid
subjectstring required
topic_idstring uuid nullable

The subject this campaign is about. A contact who unsubscribed from the topic is excluded WHATEVER the audience type — a topic opt-out is a standing answer, not an audience filter, so it cannot be routed around by selecting a different audience. Ignored for TRANSACTIONAL campaigns, which a marketing preference does not cancel.

Response

Campaign created

audience_type'ALL' | 'FILTERED' | 'SEGMENT' | 'LIST' required
created_atstring date-time required
idstring uuid required
list_idstring uuid nullable required
namestring required
scheduled_atstring date-time nullable required
sent_atstring date-time nullable required
status'DRAFT' | 'SCHEDULED' | 'SENDING' | 'PAUSED' | 'SENT' | 'CANCELLED' required
subjectstring required
topic_idstring uuid nullable required

Changes

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