> ## Documentation Index
> Fetch the complete documentation index at: https://www.spacebring.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a campaign
> Create a campaign as a draft, which an administrator sends from the admin web portal: the API cannot send, test, or schedule a campaign. A draft can be saved before its content is complete. A campaign created with basic authentication has no createdBy. With bearer token authentication, the user must be an administrator who can manage campaigns in every location of the audience. OAuth
Required scopes: campaigns
## OpenAPI
````yaml /assets/openapi.json post /campaigns/v1
openapi: 3.0.2
info:
title: Spacebring
version: 1.0.0
termsOfService: https://www.spacebring.com/terms
servers:
- url: https://api.spacebring.com
security: []
paths:
/campaigns/v1:
post:
tags:
- Campaigns
summary: Create a campaign
description: >-
Create a campaign as a draft, which an administrator sends from the
admin web portal: the API cannot send, test, or schedule a campaign. A
draft can be saved before its content is complete. A campaign created
with basic authentication has no createdBy. With bearer
token authentication, the user must be an administrator who can manage
campaigns in every location of the audience. OAuth
Required
scopes: campaigns
operationId: createCampaign
parameters:
- in: header
name: spacebring-network-id
schema:
type: string
format: uuid
required: false
description: >-
The id of the network. Required when using bearer token
authentication
requestBody:
$ref: '#/components/requestBodies/createCampaign'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/getCampaign'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/responseError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/responseError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/responseError'
security:
- BasicAuth: []
- OAuth2:
- campaigns
components:
requestBodies:
createCampaign:
content:
application/json:
schema:
type: object
properties:
campaign:
type: object
properties:
audience:
type: object
properties:
locationRefs:
description: >-
IDs of the locations whose active members the rules
choose from.
minItems: 1
type: array
items:
type: string
format: uuid
rules:
description: >-
Rules a member or nonmember of the locations has to
match at least one of. Defaults to none, which reaches
every active member of the locations.
maxItems: 20
type: array
items:
oneOf:
- type: object
properties:
companyRefs:
description: IDs of the companies whose people match.
minItems: 1
maxItems: 500
type: array
items:
type: string
format: uuid
type:
type: string
enum:
- companies
description: People of the given companies.
required:
- companyRefs
- type
- type: object
properties:
eventRefs:
description: IDs of the events whose attendees match.
minItems: 1
maxItems: 500
type: array
items:
type: string
format: uuid
type:
type: string
enum:
- eventAttendees
description: >-
Attendees of the given events, not their
hosts.
required:
- eventRefs
- type
- type: object
properties:
membershipTypes:
description: >-
Membership types whose customers match:
member, nonmember, or both.
minItems: 1
type: array
items:
type: string
enum:
- member
- nonmember
type:
type: string
enum:
- membershipTypes
description: >-
Everyone at the locations with one of the
given membership types.
required:
- membershipTypes
- type
- type: object
properties:
type:
type: string
enum:
- people
description: The given people.
userRefs:
description: >-
IDs of the users who match, the user IDs of
user customers.
minItems: 1
maxItems: 500
type: array
items:
type: string
format: uuid
required:
- type
- userRefs
- type: object
properties:
planRefs:
description: IDs of the plans whose holders match.
minItems: 1
maxItems: 500
type: array
items:
type: string
format: uuid
type:
type: string
enum:
- plans
description: >-
People holding an active subscription to one
of the given plans, personally or through
their company.
required:
- planRefs
- type
- type: object
properties:
tierRefs:
description: >-
IDs of the resource tiers whose holders
match.
minItems: 1
maxItems: 500
type: array
items:
type: string
format: uuid
type:
type: string
enum:
- resourceTiers
description: >-
People holding an active subscription to one
of the given resource tiers, personally or
through their company.
required:
- tierRefs
- type
required:
- locationRefs
description: >-
Who receives the campaign. An update replaces the whole
audience with this one.
channel:
type: string
enum:
- email
- push
description: >-
Channel the campaign is sent through. It is sent with the
content of its channel only. To reach people by email and
push, create two campaigns.
email:
type: object
properties:
body:
default: ''
description: >-
Body of the email, in the same markdown as a Feed
post. It can hold the variables {customer.name},
{customer.surname}, {customer.companyTitle}, filled in
for each recipient. Can be empty in a draft, but is
needed to send it.
type: string
maxLength: 20000
buttonLabel:
description: >-
Label of the button below the body, given together
with buttonUrl. It can hold the variables
{customer.name}, {customer.surname},
{customer.companyTitle}, filled in for each recipient.
type: string
maxLength: 60
buttonUrl:
description: >-
https link the button opens, given together with
buttonLabel.
type: string
format: uri
replyTo:
description: >-
Address replies go to. Defaults to the network's email
when omitted.
type: string
format: email
subject:
default: ''
description: >-
Subject of the email. It can hold the variables
{customer.name}, {customer.surname},
{customer.companyTitle}, filled in for each recipient.
Can be empty in a draft, but is needed to send it.
type: string
maxLength: 200
description: >-
Email content, used when the channel is email. An update
replaces the whole email with this one, so send every
field to keep.
name:
type: string
minLength: 1
maxLength: 200
description: Name of the campaign, shown to admins only.
push:
type: object
properties:
body:
default: ''
description: >-
Body of the push notification. Can be empty in a
draft, but is needed to send it.
type: string
maxLength: 1000
link:
description: >-
Link to a member web portal page, under /suite, that
the notification opens in the member app. The member
app home when omitted.
type: string
maxLength: 2000
title:
default: ''
description: >-
Title of the push notification. Can be empty in a
draft, but is needed to send it.
type: string
maxLength: 100
description: >-
Push content, used when the channel is push. An update
replaces the whole push with this one, so send every field
to keep.
required:
- audience
- channel
- name
description: The campaign to create as a draft.
required:
- campaign
required: true
schemas:
getCampaign:
type: object
properties:
campaign:
type: object
properties:
audience:
type: object
properties:
locationRefs:
type: array
items:
type: string
format: uuid
description: >-
IDs of the locations whose active members the rules choose
from.
rules:
type: array
items:
oneOf:
- type: object
properties:
companyRefs:
type: array
items:
type: string
format: uuid
description: IDs of the companies whose people match.
type:
type: string
enum:
- companies
description: Members of the given companies.
required:
- companyRefs
- type
additionalProperties: false
- type: object
properties:
eventRefs:
type: array
items:
type: string
format: uuid
description: IDs of the events whose attendees match.
type:
type: string
enum:
- eventAttendees
description: Attendees of the given events.
required:
- eventRefs
- type
additionalProperties: false
- type: object
properties:
membershipTypes:
type: array
items:
type: string
enum:
- member
- nonmember
description: Membership types whose customers match.
type:
type: string
enum:
- membershipTypes
description: >-
Everyone at the locations with one of the given
membership types.
required:
- membershipTypes
- type
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- people
description: The given people.
userRefs:
type: array
items:
type: string
format: uuid
description: IDs of the users who match.
required:
- type
- userRefs
additionalProperties: false
- type: object
properties:
planRefs:
type: array
items:
type: string
format: uuid
description: IDs of the plans whose holders match.
type:
type: string
enum:
- plans
description: >-
People holding an active subscription to one of
the given plans, personally or through their
company.
required:
- planRefs
- type
additionalProperties: false
- type: object
properties:
tierRefs:
type: array
items:
type: string
format: uuid
description: IDs of the resource tiers whose holders match.
type:
type: string
enum:
- resourceTiers
description: >-
People holding an active subscription to one of
the given resource tiers, personally or through
their company.
required:
- tierRefs
- type
additionalProperties: false
description: >-
Rules a member or nonmember of the locations has to match at
least one of. A person who matches several rules gets one
message. With no rules, every active member of the locations
matches, and no nonmember.
required:
- locationRefs
- rules
additionalProperties: false
description: Who receives the campaign.
channel:
type: string
enum:
- email
- push
description: Channel the campaign is sent through.
charge:
description: >-
What sending cost, debited from the network balance when sending
started. Present for sent email campaigns.
type: object
properties:
amount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Amount debited, in minor units of the currency.
currencyCode:
type: string
description: ISO 4217 currency code of the amount.
required:
- amount
- currencyCode
additionalProperties: false
createDate:
type: string
format: date-time
description: ISO timestamp of when the campaign was created.
createdBy:
description: >-
Admin who created the campaign. Absent for a campaign created
with client credentials.
type: object
properties:
id:
type: string
format: uuid
description: ID of the admin who created the campaign.
required:
- id
additionalProperties: false
email:
description: Email content, used when the channel is email.
type: object
properties:
body:
type: string
description: Body of the email, in the same markdown as a Feed post.
buttonLabel:
description: Label of the button below the body.
type: string
buttonUrl:
description: Link the button opens.
type: string
replyTo:
description: >-
Address replies go to. Defaults to the network's email when
omitted.
type: string
subject:
type: string
description: Subject of the email.
required:
- body
- subject
additionalProperties: false
id:
type: string
format: uuid
description: Unique identifier of the campaign.
name:
type: string
description: Name of the campaign, shown to admins only.
push:
description: Push content, used when the channel is push.
type: object
properties:
body:
type: string
description: Body of the push notification.
link:
description: >-
Link to the member web portal page the notification opens in
the member app. The member app home when omitted.
type: string
title:
type: string
description: Title of the push notification.
required:
- body
- title
additionalProperties: false
scheduleDate:
description: ISO timestamp of when the campaign is scheduled to be sent.
type: string
format: date-time
sendDate:
description: ISO timestamp of when sending started.
type: string
format: date-time
stats:
type: object
properties:
bounced:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients whose email bounced.
clicked:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Number of recipients who clicked a link in the email at
least once.
complained:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients who marked the email as spam.
delivered:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients whose mail server accepted the email.
opened:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients who opened the email at least once.
recipients:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Number of people the campaign was sent to. Zero until
sending starts.
required:
- bounced
- clicked
- complained
- delivered
- opened
- recipients
additionalProperties: false
description: Delivery statistics of the campaign.
status:
type: string
enum:
- draft
- scheduled
- sending
- sent
- canceled
- failed
description: Stage of the campaign.
updateDate:
type: string
format: date-time
description: ISO timestamp of when the campaign was last changed.
required:
- audience
- channel
- createDate
- id
- name
- stats
- status
- updateDate
additionalProperties: false
description: The campaign.
required:
- campaign
additionalProperties: false
responseError:
type: object
properties:
message:
type: string
type:
type: string
securitySchemes:
BasicAuth:
type: http
description: >-
See our [authentication
documentation](https://www.spacebring.com/docs/developer/api/authentication#basic-authentication)
for how to authorize your requests
scheme: basic
OAuth2:
type: oauth2
description: >-
See our [authentication
documentation](https://www.spacebring.com/docs/developer/api/authentication#oauth2)
for how to authorize your requests
flows:
authorizationCode:
authorizationUrl: https://oauth2.spacebring.com/api/oauth2/authorize
tokenUrl: https://oauth2.spacebring.com/api/oauth2/token
refreshUrl: https://oauth2.spacebring.com/api/oauth2/token
scopes:
benefits.readonly: Read benefits and applications
benefits: Read and write benefits and applications
campaigns.readonly: Read campaigns
campaigns: Read and write campaigns
checkIns.readonly: Read check-ins
checkIns: Read and write check-ins
community.readonly: Read community companies and memberships
community: Read and write community companies and memberships
events.readonly: Read events and tickets
events: Read and write events and tickets
feed.readonly: Read feed posts
feed: Read and write feed posts
invoices.readonly: Read contracts, credit notes, discounts and invoices
invoices: Read and write contract, credit notes, discounts and invoices
locations.readonly: Read locations
locations: Read and write locations
plans.readonly: Read plans
plans: Read and write plans
resources.readonly: Read resources and bookings
resources: Read and write resources and bookings
subscriptions.readonly: Read subscriptions
subscriptions: Read and write subscriptions
shop.readonly: Read products and orders
shop: Read and write products and orders
support.readonly: Read support tickets
support: Read and write support tickets
transactions.readonly: Read transactions
transactions: Read and write transactions
visitors.readonly: Read visitors
visitors: Read and write visitors
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.