Create a project

Creates a project with a slug unique among live projects and the given settings (the rest default), and records project.created. Admin keys only.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

CreateProjectRequest object
namestringrequired

What people call the project: 1 to 128 characters, trimmed.

example Acme News
slugstringrequired

Unique among live projects: 3 to 63 lower-case letters, digits and -. It never changes.

pattern ^[a-z0-9-]{3,63}$ · example acme-news
settingsProjectSettingsInput

Settings to set; the rest are defaults.
11 fields
- ProjectSettingsInput object
- auto_footerboolean
  
  Add an unsubscribe footer when a template has none.
- brandingBrandingInput
  
  Branding of the public pages to set.
  4 fields
  
  BrandingInput object
  
  brand_namestring | null
  
  The name the pages show, 1 to 128 characters.
  
  languagestring
  
  en or ru.
  
  example ru
  
  support_emailstring · email | null
  
  The address the pages give for questions.
  
  text_overridesmap of string → string
  
  Texts of the pages by key, replacing every override at once: at most 64, keys [a-z][a-z0-9_]*, texts 1 to 2000 characters.
- daily_send_quotainteger · int64 | null
  
  Most messages a day, 1 or more; null: no quota.
  
  1–4294967295
- default_throttle_per_hourinteger · int64 | null
  
  Default campaign speed, messages an hour; null: no limit.
  
  1–4294967295
- dns_credentialsDnsCredentialsInput
  
  DNS-provider credentials of the project. Write-only: a read never returns them.
  1 fields
  
  DnsCredentialsInput object
  
  porkbunPorkbunCredentialsBody | null
  
  Porkbun credentials; set them, null clears them, absent keeps them. They override the node’s global [dns.porkbun].
  
  2 fields
  
  PorkbunCredentialsBody object · all fields required
  
  api_keystring
  
  secret_api_keystring
- from_emailstring · email | null
  
  Default sender address of campaigns.
  
  example news@acme.example
- from_namestring | null
  
  Default sender name of campaigns, 1 to 128 characters, no line breaks.
  
  example Acme News
- reply_tostring · email | null
  
  Default Reply-To.
- soft_bounce_suppress_afterinteger · int64 | null
  
  Soft bounces in a row after which an address is suppressed; null: off.
  
  1–4294967295
- trackingTrackingInput
  
  Tracking defaults to set.
  2 fields
  
  TrackingInput object
  
  clicksboolean
  
  Click redirects.
  
  opensboolean
  
  Open pixel.
- transportstring | null
  
  Default transport: direct or relay:<name> of a relay the node offers (GET /api/v1/server); null: the node’s default.
  
  example direct

Responses

201

The project

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.
`Location`	string	The project’s URL

Project object · all fields required
created_atstring · date-time
deleted_atstring · date-time | null

When the project was deleted; null while it is live. A deleted project can only be read.
idstring · uuid

example 01900000-0000-7000-8000-000000000001
namestring

example Acme News
settingsProjectSettings

A project’s settings, every field present.
11 fields
- ProjectSettings object · all fields required
- auto_footerboolean
  
  Add an unsubscribe footer when a template has none.
- brandingBranding
  
  How the public pages look.
  4 fields
  
  Branding object · all fields required
  
  brand_namestring | null
  
  languageLanguage
  
  The language of the public pages.
  
  en
  ru
  
  support_emailstring · email | null
  
  text_overridesmap of string → string
  
  Texts of the pages by key.
- daily_send_quotainteger · int32 | null
  
  Most messages a day; null: no quota.
  
  ≥ 0
- default_throttle_per_hourinteger · int32 | null
  
  Default campaign speed, messages an hour; null: no limit.
  
  ≥ 0
- dns_credentialsDnsCredentials
  
  Which DNS providers the project set its own credentials for; the credentials are never returned.
  1 fields
  
  DnsCredentials object · all fields required
  
  porkbunboolean
  
  Whether the project set its own Porkbun credentials.
- from_emailstring · email | null
  
  Default sender address of campaigns.
- from_namestring | null
  
  Default sender name of campaigns.
- reply_tostring · email | null
  
  Default Reply-To.
- soft_bounce_suppress_afterinteger · int32 | null
  
  Soft bounces in a row after which an address is suppressed; null: off.
  
  ≥ 0
- trackingTracking
  
  What campaigns track by default.
  2 fields
  
  Tracking object · all fields required
  
  clicksboolean
  
  opensboolean
- transportstring | null
  
  Default transport, direct or relay:<name>; null: the node’s delivery.default_transport.
slugstring

example acme-news
updated_atstring · date-time

The latest change: creation, rename, settings, deletion.

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

Not an admin key (forbidden)

Problem (application/problem+json)

409

The slug is taken (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): unknown_field, required, invalid_type, invalid, out_of_range, unknown_relay; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)