Schemas

AddSendingDomainRequest

• object
• dns_providerDnsProviderrequired

  Who applies the records: porkbun, or manual for entry by hand.

  • porkbun
  • manual
• domainstringrequired

  The domain of the sender addresses: a host name, a subdomain or an international name (kept in punycode).

  example news.example.com

• bounce_subdomainstring

  The domain of the return path (MAIL FROM), below domain; left out: bounce.<domain>.

  example bounce.news.example.com

• dkim_selectorstring

  The DKIM selector: labels of letters, digits and inner hyphens, at most 63 characters; left out: pw1.

  example pw1

• ip_poolstring

  The IP pool of the node’s config to send from (GET /api/v1/server lists them); left out: default.

  example default

• tracking_hoststring | null

  A host for tracking and unsubscribe links; null or left out: none (links use the node’s web.public_url).

  example links.example.com

Used by: add_sending_domain (request)

AddedSendingDomain

• object · extends SendingDomain · all fields required
• bounce_subdomainstring

  example bounce.news.example.com

• checksarray of DomainCheck

  One entry per check that ran, in the canonical order; empty until the domain is first verified.

  see DomainCheck

• created_atstring · date-time
• dkim_public_keystring

  The DKIM public key: base64 of its DER SubjectPublicKeyInfo, the p= of the DKIM record (RSA 2048).

• dkim_selectorstring

  example pw1

• dns_providerDnsProvider

  Who applies a domain’s DNS records.

  • porkbun
  • manual
• domainstring

  In punycode for an international name.

  example news.example.com

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• ip_poolstring

  example default

• last_checked_atstring · date-time | null

  When the records were last checked (RFC 3339); null until then.

• project_idstring · uuid
• required_recordsarray of RequiredRecord

  What to create in DNS, in this order.

  see RequiredRecord

• statusDomainStatus

  Where a sending domain stands.

  • pending
  • verified
  • failed
• tracking_hoststring | null

  null: none.

• updated_atstring · date-time

Used by: add_sending_domain (201)

ApiKey

• object · all fields required
• created_atstring · date-time
• expires_atstring · date-time | null

  null: never.

• idstring · uuid

  What revoking the key takes.

  example 01900000-0000-7000-8000-000000000001

• kindApiKeyKind

  The kind of an API key.

  • admin
  • project
• last_used_atstring · date-time | null

  When the key was last used; null: not recorded yet.

• namestring

  example billing backend

• prefixstring

  The public part of the key string, pw_<adm|prj>_<prefix>_...: how to tell which key a client holds.

  example 1a2b3c4d

• project_idstring · uuid | null

  The key’s project; null for an admin key.

• revoked_atstring · date-time | null

  When the key was revoked; null while it is not.

• scopesarray of Scope

  What the key may do; every scope for an admin key.

ApiKeyKind

string · enum

• admin
• project

ApiKeyList

• object · all fields required
• itemsarray of ApiKey

  In id order; revoked and expired keys included.

  see ApiKey

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_admin_keys (200), list_api_keys (200)

AppliedDnsRecord

• object · all fields required
• contentstring

  The value the record should hold.

• detailstring | null

  A message for the outcomes that carry one (conflict, provider_error, unavailable); null otherwise.

• namestring

  The owner name, without a trailing dot.

  example bounce.news.example.com

• outcomeDnsApplyOutcome

  What apply did to one record.

  • created
  • updated
  • unchanged
  • skipped_exists
  • manual
  • conflict
  • provider_error
  • unavailable
• purposeRecordPurpose

  What a required record is for.

  • spf_bounce
  • mx_bounce
  • dkim
  • dmarc
  • tracking_cname
• typeRecordType

  The type of a DNS record.

  • txt
  • mx
  • cname

AppliedDnsRecords

• object · all fields required
• dns_providerDnsProvider

  Who applied the records: porkbun, or manual (nothing was changed; each record’s outcome is manual).

  • porkbun
  • manual
• recordsarray of AppliedDnsRecord

  One entry per required record, in the order they are created.

  see AppliedDnsRecord

Used by: apply_dns_records (200)

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.

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.

Campaign

• object · all fields required
• completed_atstring · date-time | null
• created_atstring · date-time
• from_emailstring · email | null

  null: the project’s settings.from_email.

• from_namestring | null

  null: the project’s settings.from_name.

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• last_errorstring | null

  Why the launch failed; null unless failed.

• launched_atstring · date-time | null
• list_idsarray of string

  In the order given.

• namestring

  example Spring sale

• partial_versionsmap of string → integer · int32

  The versions of the partials fixed at launch, by name; {} before.

• project_idstring · uuid
• reply_tostring · email | null

  null: the project’s settings.reply_to.

• scheduled_atstring · date-time | null

  When a scheduled campaign launches; null unless scheduled.

• shard_countinteger · int32 | null

  Fixed at launch; null before.

  ≥ 0

• statusstring

  draft, scheduled, launching, sending, paused, completed, cancelled or failed.

  example draft

• subject_overridestring | null

  null: the template’s subject.

• template_idstring · uuid
• template_versioninteger · int32 | null

  The template’s version fixed at launch; null before.

  ≥ 0

• throttle_per_hourinteger · int32 | null

  null: the project’s default_throttle_per_hour, or no limit.

  ≥ 0

• total_recipientsinteger · int64 | null

  Recipients of the launch’s snapshot; null before.

  ≥ 0

• tracking_overrideTrackingOverride | null

  null: the project’s settings.tracking.

  see TrackingOverride

• transport_overridestring | null

  null: the project’s transport, then the node’s default.

• updated_atstring · date-time

  The latest change: creation, fields, status.

Used by: create_campaign (201), get_campaign (200), update_campaign (200), cancel_campaign (200), launch_campaign (200), pause_campaign (200), resume_campaign (200)

CampaignDeliveryCounts

• object · all fields required
• bouncedinteger · int64

  Refused for good at RCPT (a hard bounce).

  ≥ 0

• cancelledinteger · int64

  Not sent: the campaign was cancelled.

  ≥ 0

• deferredinteger · int64

  Refused for now; tried again later.

  ≥ 0

• failedinteger · int64

  Refused for good otherwise, out of attempts, or not made.

  ≥ 0

• queuedinteger · int64

  Waiting for their first attempt.

  ≥ 0

• sentinteger · int64

  Taken by the recipient’s server.

  ≥ 0

• suppressedinteger · int64

  Held back by a suppression or the subscriber’s status.

  ≥ 0

• totalinteger · int64

  Every delivery: the sum of the above.

  ≥ 0

CampaignEventCounts

• object · all fields required
• totalinteger · int64

  Every event, repeats included.

  ≥ 0

• uniqueinteger · int64

  The distinct subscribers of those events.

  ≥ 0

CampaignList

• object · all fields required
• itemsarray of Campaign

  In creation order.

  see Campaign

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_campaigns (200)

CampaignPreflight

• object · all fields required
• campaign_idstring · uuid
• domainCampaignPreflightDomain | null

  The project’s sending domain of the sender; null when it has none.

  see CampaignPreflightDomain

• estimated_duration_secsinteger · int64 | null

  How long sending takes at throttle_per_hour, in seconds; null without a limit or a count.

  ≥ 0

• from_emailstring · email | null

  The sender: the campaign’s, else the project’s settings.from_email; null when neither names one.

• recipientsinteger · int64 | null

  Recipients after deduplication and suppression: the deliveries the launch would write. null when a list is missing or deleted.

  ≥ 0

• throttle_per_hourinteger · int32 | null

  Most messages an hour: the campaign’s, else the project’s default_throttle_per_hour; null: no limit.

  ≥ 0

• transportstring

  The transport the messages go through: direct or relay:<name>.

  example direct

• violationsarray of ProblemFieldError

  Every unmet precondition of the launch, as 422 precondition_failed would list them; empty: it can be launched.

  see ProblemFieldError

Used by: preflight_campaign (200)

CampaignPreflightDomain

• object · all fields required
• domainstring

  example acme.example

• idstring · uuid
• statusstring

  pending, verified or failed; only a verified one sends.

  example verified

• warningsarray of CampaignPreflightWarning

  Checks that do not decide the status and are not ok (ptr, tracking_tls): the launch goes ahead, delivery may suffer.

  see CampaignPreflightWarning

CampaignPreflightWarning

• object · all fields required
• checkstring

  example ptr

• detailstring | null
• statusstring

  missing, mismatch or warning.

  example warning

CampaignStats

• object · all fields required
• campaign_idstring · uuid
• clicksCampaignEventCounts

  Its clicks: follows of its tracked links (message.clicked).

  see CampaignEventCounts

• deliveriesCampaignDeliveryCounts

  Its deliveries by status.

  see CampaignDeliveryCounts

• opensCampaignEventCounts

  Its opens: loads of the open pixel (message.opened).

  see CampaignEventCounts

• statusstring

  The campaign’s status now.

  example sending

• total_recipientsinteger · int64 | null

  How many recipients its launch wrote; null before the launch.

  ≥ 0

Used by: get_campaign_stats (200)

CheckStatus

string · enum

• ok
• missing
• mismatch
• warning

CreateAdminKeyRequest

• object
• namestringrequired

  What the key is for: 1 to 128 characters, trimmed.

  example ops

• expires_atstring · date-time | null

  When the key stops working, RFC 3339, later than now; null or left out: never.

Used by: create_admin_key (request)

CreateApiKeyRequest

• object
• namestringrequired

  What the key is for: 1 to 128 characters, trimmed.

  example billing backend

• scopesarray of Scoperequired

  What the key may do: at least one scope, each once. A project key grants only scopes it holds itself.

  example ["read","write"]

• expires_atstring · date-time | null

  When the key stops working, RFC 3339, later than now; null or left out: never. A project key that expires grants no later expiry.

  example 2027-01-01T00:00:00Z

Used by: create_api_key (request)

CreateCampaignRequest

• object
• list_idsarray of stringrequired

  The lists it goes to: 1 to 16 distinct ids of live lists of the project. A recipient on several is sent once, as a subscriber of the first.

  1–16 items

• namestringrequired

  What people call the campaign: 1 to 128 characters, trimmed. Two campaigns may share a name.

  example Spring sale

• template_idstring · uuidrequired

  The template it sends: the id of a message template of the project.

• from_emailstring · email | null

  example news@acme.example

• from_namestring | null

  example Acme News

• reply_tostring · email | null
• subject_overridestring | null

  The subject source in place of the template’s.

• throttle_per_hourinteger · int64 | null

  Most messages an hour, 1 to 4294967295.

  1–4294967295

• tracking_overrideTrackingOverrideInput | null

  What a campaign tracks in place of the project’s settings.tracking.

  see TrackingOverrideInput

• transport_overridestring | null

  direct or relay:<name> (a relay of the node).

  example direct

Used by: create_campaign (request)

CreateListRequest

• object
• namestringrequired

  What people call the list: 1 to 128 characters, trimmed. Two lists may share a name.

  example Weekly news

• confirmation_template_idstring · uuid | null

  The template of the confirmation letter: the id of a message template of the project; required with double_opt_in. null or left out: none.

• double_opt_inboolean

  Subscribers confirm by a link before they get campaigns; default false. Needs confirmation_template_id.

• from_overrideFromOverrideInput | null

  The sender of the list’s own letters (confirmations) in place of the project’s; null or left out: the project’s.

  see FromOverrideInput

Used by: create_list (request)

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.

  see ProjectSettingsInput

Used by: create_project (request)

CreateSubscriberRequest

• object · all fields required
• attributesobject

  Attributes to set: a map of string, number or boolean values. null for a key removes it. Up to 64 keys, up to 4 KB of JSON.

• emailstring · email

  The address; any case and surrounding whitespace are normalized.

  example ann@example.com

Used by: add_subscriber (request)

CreateSuppressionRequest

• object
• emailstring · emailrequired

  The address; any case and surrounding whitespace are normalized.

  example ann@example.com

• scopestringrequired

  project (every list) or list:<list_id> (one list of this project).

  example project

• reasonstring | null

  manual, the only reason a client gives (the default).

  example manual

Used by: add_suppression (request)

CreateTemplateRequest

• object
• html_bodystringrequired

  The HTML body: 1 byte to 1 MiB. Values are HTML-escaped. A message’s must show {{ unsubscribe_url }}, itself or through the partials it includes, when the project’s auto_footer is false.

  example <p>Hi!</p><a href="{{ unsubscribe_url }}">Unsubscribe</a>

• namestringrequired

  Unique in the project: 1 to 128 characters, trimmed.

  example Welcome

• kindTemplateKind | null

  message (the default) or partial: a fragment without a subject that other templates include as {% include "name" %}.

  • message
  • partial
• subjectstring | null

  The subject, a template too: 1 to 998 characters, one line. A message needs one; a partial has none.

  example Welcome, {{ subscriber.attributes.first_name|default('friend') }}

• text_bodystring | null

  The text body: 1 byte to 1 MiB; null or left out: made from the HTML when the message is sent.

Used by: create_template (request)

CreatedApiKey

• object · all fields required
• created_atstring · date-time
• expires_atstring · date-time | null
• idstring · uuid
• keystring | null

  The key string to send as Authorization: Bearer. It is not stored and no other answer shows it: keep it now. null in a replay (Idempotent-Replayed: true) of a request sent again with the same Idempotency-Key: the key was created by the first request, whose answer carried its string; revoke it and create another with a new Idempotency-Key if that answer was lost.

  example pw_prj_1a2b3c4d_...

• kindApiKeyKind

  The kind of an API key.

  • admin
  • project
• last_used_atstring · date-time | null
• namestring
• prefixstring
• project_idstring · uuid | null
• revoked_atstring · date-time | null
• scopesarray of Scope

Used by: create_admin_key (201), create_api_key (201)

DnsApplyOutcome

string · enum

• created
• updated
• unchanged
• skipped_exists
• manual
• conflict
• provider_error
• unavailable

DnsCredentials

• object · all fields required
• porkbunboolean

  Whether the project set its own Porkbun credentials.

DnsCredentialsInput

• object
• porkbunPorkbunCredentialsBody | null

  Porkbun credentials; set them, null clears them, absent keeps them. They override the node’s global [dns.porkbun].

  see PorkbunCredentialsBody

DnsProvider

string · enum

• porkbun
• manual

DomainCheck

• object · all fields required
• detailstring | null

  What was found instead of what was expected; null when ok.

• namestring

  spf_bounce, mx_bounce, dkim, dmarc, tracking_cname, tracking_tls or ptr.

  example dkim

• statusCheckStatus

  How one verification check came out.

  • ok
  • missing
  • mismatch
  • warning

DomainStatus

string · enum

• pending
• verified
• failed

Event

• object · all fields required
• event_idstring · uuid
• list_idstring · uuid | null

  The list the event is about; null for none.

• payloadobject

  What the event says, by type: plain values (strings, integers, booleans, null); actor_key_id is the key that acted.

• project_idstring · uuid
• subscriber_idstring · uuid | null

  The subscriber the event is about; null for none.

• tsstring · date-time
• typestring

  subscriber.created, subscriber.unsubscribed, subscriber.resubscribed, subscriber.reactivated, …

  example subscriber.created

FromOverride

• object · all fields required
• from_emailstring · email
• from_namestring | null

  null: the project’s settings.from_name.

FromOverrideInput

• object
• from_emailstring · emailrequired

  The sender address.

  example news@acme.example

• from_namestring | null

  The sender name, 1 to 128 characters, no line breaks; null or left out: the project’s settings.from_name.

  example Acme News

ImportSubscribersRequest

• object · all fields required
• subscribersarray of CreateSubscriberRequest

  The records, up to 10 000, in order; the response names an invalid one by its index here.

  ≤ 10000 items

  see CreateSubscriberRequest

Used by: import_subscribers (request)

InvalidImportRecord

• object · all fields required
• codestring

  invalid or invalid_type, as in errors of a 422.

  example invalid

• emailstring

  The email as the record had it.

• fieldstring

  The record’s field: email, attributes or attributes.<key>.

  example email

• indexinteger

  The record’s index in subscribers, from 0.

  ≥ 0

• messagestring

IpPool

• object · all fields required
• address_countinteger

  ≥ 0 · example 1

• addressesarray of IpPoolAddress | null

  The addresses; shown to an admin key only, null for a project key.

  see IpPoolAddress

• namestring

  example default

IpPoolAddress

• object · all fields required
• hostnamestring

  The EHLO name; the address’s PTR points to it.

  example mx1.example.com

• ipstring | null

  The local address the node sends from; null: the system route behind NAT.

  example 203.0.113.10

• public_ipstring | null

  The public address behind NAT; null when there is no NAT.

Language

string · enum

• en
• ru

List

• object · all fields required
• confirmation_template_idstring · uuid | null

  The template of the confirmation letter; null: none.

• created_atstring · date-time
• deleted_atstring · date-time | null

  When the list was deleted; null while it is live. A deleted list can only be read.

• double_opt_inboolean

  Subscribers confirm by a link before they get campaigns.

• from_overrideFromOverride | null

  The sender of the list’s own letters; null: the project’s.

  see FromOverride

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• namestring

  example Weekly news

• project_idstring · uuid

  The list’s project.

• updated_atstring · date-time

  The latest change: creation, name, options, deletion.

Used by: create_list (201), get_list (200), update_list (200)

ListList

• object · all fields required
• itemsarray of List

  In creation order.

  see List

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_lists (200)

PorkbunCredentialsBody

• object · all fields required
• api_keystring
• secret_api_keystring

PreviewPart

string · enum

• subject
• html
• text

PreviewTemplateRequest

• object
• sample_attributesobject | null

  Attributes to render with, as a subscriber’s: string, number or boolean values, up to 64 keys, up to 4 KB of JSON; any other attribute the template names is undefined. Not with subscriber_id; null or left out: none.

• subscriber_idstring · uuid | null

  A subscriber of the project: its email, attributes and list name. Not with sample_attributes; null or left out: none.

Used by: preview_template (request)

PreviewWarning

• object · all fields required
• codestring

  subscriber_not_active, subscriber_list_deleted, empty_subject, html_too_large, auto_footer_added, text_from_html.

  example auto_footer_added

• messagestring
• partPreviewPart | null

  The part it is about; null: the message as a whole.

  • subject
  • html
  • text

Problem

• object
• codestringrequired

  The error code, stable; the table is in docs/spec/07-api.md.

  example key_invalid

• detailstringrequired

  What went wrong this time, for people.

  example the API key is not valid

• statusinteger · int32required

  The HTTP status code.

  ≥ 0 · example 401

• titlestringrequired

  A short summary, the same for every occurrence of the code.

  example API key invalid

• typestringrequired

  https://postwind.dev/errors/<code>.

  example https://postwind.dev/errors/key_invalid

• errorsarray of ProblemFieldError

  Every invalid field or unmet precondition (422 only); left out otherwise.

  see ProblemFieldError

Used by: get_server_info (401, 429, 504), whoami (401, 429, 504), list_projects (401, 403, 422, 429, 504), create_project (400, 401, 403, 409, 413, 415, 422, 429, 504), get_project (401, 403, 404, 429, 504), update_project_settings (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), delete_project (401, 403, 404, 429, 504), list_admin_keys (401, 403, 422, 429, 504), create_admin_key (400, 401, 403, 409, 413, 415, 422, 429, 504), revoke_admin_key (401, 403, 404, 409, 429, 504), list_api_keys (401, 403, 404, 422, 429, 504), create_api_key (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), revoke_api_key (401, 403, 404, 409, 429, 504), list_lists (401, 403, 404, 422, 429, 504), create_list (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_list (401, 403, 404, 429, 504), update_list (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), delete_list (401, 403, 404, 409, 429, 504), list_subscribers (401, 403, 404, 422, 429, 504), add_subscriber (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), find_subscriber (401, 403, 404, 429, 504), import_subscribers (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_subscriber (401, 403, 404, 429, 504), update_subscriber_attributes (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), erase_subscriber (401, 403, 404, 409, 429, 504), get_subscriber_events (401, 403, 404, 422, 429, 504), reactivate_subscriber (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), resubscribe_subscriber (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), unsubscribe_subscriber (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), list_suppressions (401, 403, 404, 422, 429, 504), add_suppression (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), remove_suppression (401, 403, 404, 409, 422, 429, 504), list_sending_domains (401, 403, 404, 422, 429, 504), add_sending_domain (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_sending_domain (401, 403, 404, 429, 504), update_sending_domain (400, 401, 403, 404, 422, 429, 504), delete_sending_domain (401, 403, 404, 409, 429, 504), apply_dns_records (401, 403, 404, 409, 422, 429, 504), get_required_dns_records (401, 403, 404, 422, 429, 504), verify_sending_domain (401, 403, 404, 409, 422, 429, 504), list_templates (401, 403, 404, 422, 429, 504), create_template (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_template (401, 403, 404, 429, 504), update_template (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), preview_template (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), send_test_email (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_template_version (401, 403, 404, 429, 504), list_campaigns (401, 403, 404, 422, 429, 504), create_campaign (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), get_campaign (401, 403, 404, 429, 504), update_campaign (400, 401, 403, 404, 409, 413, 415, 422, 429, 504), cancel_campaign (401, 403, 404, 409, 422, 429, 504), launch_campaign (401, 403, 404, 409, 422, 429, 504), pause_campaign (401, 403, 404, 409, 422, 429, 504), preflight_campaign (401, 403, 404, 409, 422, 429, 504), resume_campaign (401, 403, 404, 409, 422, 429, 504), get_campaign_stats (401, 403, 404, 429, 504)

ProblemFieldError

• object · all fields required
• codestring

  What is wrong with it, snake_case.

  example invalid

• fieldstring

  The field, as named in the request.

  example name

• messagestring

  example must not be empty

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.

  see ProjectSettings

• slugstring

  example acme-news

• updated_atstring · date-time

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

Used by: create_project (201), get_project (200), update_project_settings (200)

ProjectList

• object · all fields required
• itemsarray of Project

  In creation order.

  see Project

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_projects (200)

ProjectSettings

• object · all fields required
• auto_footerboolean

  Add an unsubscribe footer when a template has none.

• brandingBranding

  How the public pages look.

  see Branding

• 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.

  see DnsCredentials

• 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.

  see Tracking

• transportstring | null

  Default transport, direct or relay:<name>; null: the node’s delivery.default_transport.

ProjectSettingsInput

• object
• auto_footerboolean

  Add an unsubscribe footer when a template has none.

• brandingBrandingInput

  Branding of the public pages to set.

  see BrandingInput

• 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.

  see DnsCredentialsInput

• 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.

  see TrackingInput

• 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

ReactivateRequest

• object · all fields required
• reasonstring

  1 to 256 characters. Recorded in the event subscriber.reactivated.

  example the mailbox works again (ticket 4711)

Used by: reactivate_subscriber (request)

RecordPurpose

string · enum

• spf_bounce
• mx_bounce
• dkim
• dmarc
• tracking_cname

RecordType

string · enum

• txt
• mx
• cname

RejectStage

string · enum

• connect
• rcpt
• data

RequiredDnsRecords

• object · all fields required
• required_recordsarray of RequiredRecord

  What to create in DNS, in this order.

  see RequiredRecord

Used by: get_required_dns_records (200)

RequiredRecord

• object · all fields required
• contentstring

  The whole value; a TXT value over 255 characters is split into strings by the DNS provider, not here.

  example v=spf1 ip4:203.0.113.10 -all

• create_only_if_absentboolean

  Create it only if the name has no record of this type, and never change one that is there (the DMARC record).

• namestring

  The owner name, without a trailing dot.

  example bounce.news.example.com

• priorityinteger · int32 | null

  The MX priority; null for other types.

  ≥ 0 · example 10

• purposeRecordPurpose

  What a required record is for.

  • spf_bounce
  • mx_bounce
  • dkim
  • dmarc
  • tracking_cname
• typeRecordType

  The type of a DNS record.

  • txt
  • mx
  • cname

ResubscribeRequest

• object · all fields required
• consent_sourcestring

  Where the new consent came from (a form, a support ticket); 1 to 256 characters. Recorded in the event subscriber.resubscribed.

  example signup form, 2026-11-07

Used by: resubscribe_subscriber (request)

Scope

string · enum

• read
• write
• send
• keys

SendingDomain

• object · all fields required
• bounce_subdomainstring

  example bounce.news.example.com

• checksarray of DomainCheck

  One entry per check that ran, in the canonical order; empty until the domain is first verified.

  see DomainCheck

• created_atstring · date-time
• dkim_public_keystring

  The DKIM public key: base64 of its DER SubjectPublicKeyInfo, the p= of the DKIM record (RSA 2048).

• dkim_selectorstring

  example pw1

• dns_providerDnsProvider

  Who applies a domain’s DNS records.

  • porkbun
  • manual
• domainstring

  In punycode for an international name.

  example news.example.com

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• ip_poolstring

  example default

• last_checked_atstring · date-time | null

  When the records were last checked (RFC 3339); null until then.

• project_idstring · uuid
• statusDomainStatus

  Where a sending domain stands.

  • pending
  • verified
  • failed
• tracking_hoststring | null

  null: none.

• updated_atstring · date-time

Used by: get_sending_domain (200), verify_sending_domain (200)

SendingDomainList

• object · all fields required
• itemsarray of SendingDomain

  In creation order.

  see SendingDomain

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_sending_domains (200)

ServerResponse

• object · all fields required
• available_transportsarray of string

  The transports this node can send through now; a message whose transport is not here is not sent (test-send answers 422 transport_unavailable). Empty until the built-in direct and relay transports ship.

  example []

• default_transportstring

  The transport a project without its own uses.

  example direct

• dns_providersarray of string

  DNS providers a sending domain may name: manual always, porkbun when it is configured.

  example ["manual","porkbun"]

• enabled_subservicesarray of string

  Subservices enabled on this node, in start order: api, mcp, web, smtp.inbound, delivery.

  example ["api","mcp","web","smtp.inbound","delivery"]

• ip_poolsarray of IpPool

  IP pools by name, for a sending domain’s ip_pool.

  see IpPool

• transportsarray of string

  Delivery transports a project may use: direct (built in) and relay:<name> for each configured relay.

  example ["direct","relay:ses"]

• versionstring

  Postwind version and git commit, as postwind --version prints them.

  example 0.1.0 (abc1234)

Used by: get_server_info (200)

Subscriber

• object · all fields required
• attributesobject

  The subscriber’s attributes, a map of string, number or boolean values.

• confirmed_atstring · date-time | null

  When the subscriber confirmed a double opt-in; null otherwise.

• created_atstring · date-time
• emailstring · email

  example ann@example.com

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• list_idstring · uuid

  The list the subscriber is on.

• project_idstring · uuid

  The subscriber’s project.

• soft_bounce_streakinteger · int32

  Soft bounces in a row; reset by a delivery (P4+).

  ≥ 0

• sourcestring

  How the subscriber was added: api, import or confirm.

• statusstring

  pending, active, unsubscribed, bounced or complained.

  example active

• unsubscribed_atstring · date-time | null

  When the subscriber unsubscribed; null otherwise.

• updated_atstring · date-time

  The latest change: creation, an attribute merge, a status change.

Used by: add_subscriber (200, 201), find_subscriber (200), get_subscriber (200), update_subscriber_attributes (200), reactivate_subscriber (200), resubscribe_subscriber (200), unsubscribe_subscriber (200)

SubscriberEventList

• object · all fields required
• itemsarray of Event

  Oldest first: by time, then by event id.

  see Event

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: get_subscriber_events (200)

SubscriberImportReport

• object · all fields required
• createdinteger

  Records whose address was not on the list: new subscribers.

  ≥ 0

• invalidarray of InvalidImportRecord

  Records not added, by index.

  see InvalidImportRecord

• pending_confirmationinteger

  Of the created subscribers, those pending (the list has double opt-in).

  ≥ 0

• updatedinteger

  Valid records whose address was already on the list or came earlier in the batch: merged into that subscriber, its status kept.

  ≥ 0

Used by: import_subscribers (200)

SubscriberList

• object · all fields required
• itemsarray of Subscriber

  Ordered by id.

  see Subscriber

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_subscribers (200)

Suppression

• object · all fields required
• created_atstring · date-time
• emailstring · email

  example ann@example.com

• project_idstring · uuid

  The suppression’s project.

• reasonstring

  unsubscribed_all, unsubscribed_list, hard_bounce, soft_bounce_limit, complaint or manual.

  example manual

• scopestring

  project (every list) or list:<list_id>.

  example project

• sourcestring

  Where it came from: api (the API or MCP), web, delivery or inbound.

  example api

Used by: add_suppression (200, 201)

SuppressionList

• object · all fields required
• itemsarray of Suppression

  By address, then by scope.

  see Suppression

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_suppressions (200)

Template

• object · all fields required
• created_atstring · date-time

  When this version was saved.

• engineTemplateEngine

  The template engine.

  • minijinja
• html_bodystring
• idstring · uuid

  The template’s id, the same in every version.

  example 01900000-0000-7000-8000-000000000001

• kindTemplateKind

  What a template is.

  • message
  • partial
• namestring

  example Welcome

• project_idstring · uuid
• subjectstring | null

  null for a partial.

• text_bodystring | null

  null: the text is made from the HTML when the message is sent.

• versioninteger · int32

  From 1, one more at each save.

  ≥ 1 · example 2

Used by: create_template (201), get_template (200), update_template (200), get_template_version (200)

TemplateEngine

string · enum

• minijinja

TemplateKind

string · enum

• message
• partial

TemplateList

• object · all fields required
• itemsarray of TemplateSummary

  In id order, each by its latest version.

  see TemplateSummary

• next_cursorstring | null

  Pass as cursor for the next page; null on the last page.

Used by: list_templates (200)

TemplatePreview

• object · all fields required
• htmlstring

  The HTML part, with the automatic footer when it was added.

• subjectstring
• textstring

  The text part: the text body, or the HTML made into text; with the automatic footer when it was added.

• warningsarray of PreviewWarning

  see PreviewWarning

Used by: preview_template (200)

TemplateSummary

• object · all fields required
• created_atstring · date-time

  When the latest version was saved.

• idstring · uuid
• kindTemplateKind

  What a template is.

  • message
  • partial
• namestring
• project_idstring · uuid
• versioninteger · int32

  The latest version.

  ≥ 1

TestSend

• object · all fields required
• from_emailstring

  The sender: the project’s settings.from_email.

  example news@example.com

• resultsarray of TestSendResult

  One per distinct address, in the order of the request.

  see TestSendResult

• subjectstring

  The subject every message carries: [TEST] and the rendered one.

  example [TEST] Welcome, Ann

• transportstring

  The transport the messages went through: direct, relay:<name>.

  example direct

Used by: send_test_email (200)

TestSendOutcome

string · enum

• accepted
• deferred
• rejected
• suppressed
• failed

TestSendRequest

• object
• toarray of stringrequired

  1 to 10 addresses; a repeated address (after normalization) gets one message.

  example ["me@example.com"]

• sample_attributesobject | null

  Attributes to render with, as a subscriber’s: string, number or boolean values, up to 64 keys, up to 4 KB of JSON; any other attribute the template names is undefined. null or left out: every attribute is the text sample.

Used by: send_test_email (request)

TestSendResult

• object · all fields required
• emailstring

  The address, normalized.

  example me@example.com

• message_idstring | null

  The message’s Message-ID, without angle brackets; null when it was not sent (suppressed).

• outcomeTestSendOutcome

  How the test message to one address went.

  • accepted
  • deferred
  • rejected
  • suppressed
  • failed
• smtp_codeinteger · int32 | null

  The reply code of a refusal (deferred, rejected); otherwise null.

  ≥ 0 · example 550

• smtp_textstring | null

  The reply text of a refusal (deferred, rejected); otherwise null.

• stageRejectStage | null

  The stage of a rejected; otherwise null.

  • connect
  • rcpt
  • data

Tracking

• object · all fields required
• clicksboolean
• opensboolean

TrackingInput

• object
• clicksboolean

  Click redirects.

• opensboolean

  Open pixel.

TrackingOverride

• object · all fields required
• clicksboolean
• opensboolean

TrackingOverrideInput

• object · all fields required
• clicksboolean

  Click redirects.

• opensboolean

  The open pixel.

UnsubscribeRequest

• object
• scopestring | null

  list (default): from the subscriber’s list; project: from every list of the project.

  example list

Used by: unsubscribe_subscriber (request)

UpdateCampaignRequest

• object
• from_emailstring · email | null
• from_namestring | null
• list_idsarray of string

  1 to 16 distinct ids of live lists of the project.

  1–16 items

• namestring

  example Spring sale, final

• reply_tostring · email | null
• subject_overridestring | null
• template_idstring · uuid

  A message template of the project.

• throttle_per_hourinteger · int64 | null

  1–4294967295

• tracking_overrideTrackingOverrideInput | null

  What a campaign tracks in place of the project’s settings.tracking.

  see TrackingOverrideInput

• transport_overridestring | null

Used by: update_campaign (request)

UpdateListRequest

• object
• confirmation_template_idstring · uuid | null

  The template of the confirmation letter, a message template of the project; null clears it (not while double_opt_in is on).

• double_opt_inboolean

  Turn double opt-in on (needs a confirmation_template_id, the list’s or this one) or off.

• from_overrideFromOverrideInput | null

  The sender of the list’s own letters, replaced as a whole; null: the project’s.

  see FromOverrideInput

• namestring

  The new name.

  example Monthly news

Used by: update_list (request)

UpdateProjectRequest

• object
• namestring

  The new name.

  example Acme Inc

• settingsProjectSettingsInput

  Settings to change; the rest keep their values.

  see ProjectSettingsInput

Used by: update_project_settings (request)

UpdateSendingDomainRequest

• object
• dns_providerDnsProviderrequired

  Who applies the records: porkbun or manual.

  • porkbun
  • manual
• ip_poolstring

  The IP pool to send from (GET /api/v1/server lists them). Changing it moves the domain to pending.

  example default

• tracking_hoststring | null

  A host for tracking and unsubscribe links; null clears it. Changing it moves the domain to pending.

  example links.example.com

Used by: update_sending_domain (request)

UpdateSubscriberRequest

• object · all fields required
• attributesobject

  Attributes to set or remove (null).

Used by: update_subscriber_attributes (request)

UpdateTemplateRequest

• object
• html_bodystringrequired

  The HTML body, as at creation.

• subjectstring | null

  The subject, as at creation.

• text_bodystring | null

  The text body; null or left out: made from the HTML.

Used by: update_template (request)

UpdatedSendingDomain

• object · extends SendingDomain · all fields required
• bounce_subdomainstring

  example bounce.news.example.com

• checksarray of DomainCheck

  One entry per check that ran, in the canonical order; empty until the domain is first verified.

  see DomainCheck

• created_atstring · date-time
• dkim_public_keystring

  The DKIM public key: base64 of its DER SubjectPublicKeyInfo, the p= of the DKIM record (RSA 2048).

• dkim_selectorstring

  example pw1

• dns_providerDnsProvider

  Who applies a domain’s DNS records.

  • porkbun
  • manual
• domainstring

  In punycode for an international name.

  example news.example.com

• idstring · uuid

  example 01900000-0000-7000-8000-000000000001

• ip_poolstring

  example default

• last_checked_atstring · date-time | null

  When the records were last checked (RFC 3339); null until then.

• project_idstring · uuid
• required_recordsarray of RequiredRecord | null

  The records to create after an ip_pool or tracking_host change; null when the change left the domain verified or failed.

  see RequiredRecord

• statusDomainStatus

  Where a sending domain stands.

  • pending
  • verified
  • failed
• tracking_hoststring | null

  null: none.

• updated_atstring · date-time

Used by: update_sending_domain (200)

WhoamiResponse

• object · all fields required
• expires_atstring · date-time | null

  When the key stops working; null: never.

• key_idstring · uuid

  The key’s id: what revoking it takes.

  example 01900000-0000-7000-8000-000000000001

• kindApiKeyKind

  The kind of an API key.

  • admin
  • project
• namestring

  The name its owner gave it.

  example ops

• project_idstring · uuid | null

  The key’s project; null for an admin key.

• scopesarray of Scope

  What the key may do. An admin key has every scope, and may manage projects and admin keys besides.

Used by: whoami (200)