Banger API reference

List workspace products

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• namestringrequired
• slugstringrequired
• kindstringrequired

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | nullrequired
• domainsarrayrequired
• Each itemstring
• descriptionstringrequired
• contextobjectrequired
• Additional propertyAny value
• brandobjectrequired
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstringrequired

  enum: "active", "archived"

• is_defaultbooleanrequired
• route_readybooleanrequired
• setuparrayrequired
• Each itemobject
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Create a product

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• namestringrequired

  minLength: 1 · maxLength: 160

• kindstring

  default: "product" · enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | null

  maxLength: 2000

• descriptionstring

  maxLength: 4000

• contextobject
• Additional propertyAny value
• domainsarray

  maxItems: 20

• Each itemstring

  maxLength: 253

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• namestringrequired
• slugstringrequired
• kindstringrequired

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | nullrequired
• domainsarrayrequired
• Each itemstring
• descriptionstringrequired
• contextobjectrequired
• Additional propertyAny value
• brandobjectrequired
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstringrequired

  enum: "active", "archived"

• is_defaultbooleanrequired
• route_readybooleanrequired
• setuparrayrequired
• Each itemobject
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "example",
  "kind": "product",
  "website_url": "example",
  "description": "example",
  "context": {},
  "domains": [
    "example"
  ]
}'

Get a product

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• namestringrequired
• slugstringrequired
• kindstringrequired

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | nullrequired
• domainsarrayrequired
• Each itemstring
• descriptionstringrequired
• contextobjectrequired
• Additional propertyAny value
• brandobjectrequired
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstringrequired

  enum: "active", "archived"

• is_defaultbooleanrequired
• route_readybooleanrequired
• setuparrayrequired
• Each itemobject
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products/{productId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Update a product

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• namestring

  maxLength: 160

• kindstring

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | null

  maxLength: 2000

• descriptionstring

  maxLength: 4000

• contextobject
• Additional propertyAny value
• brandobject
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstring

  enum: "active", "archived"

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• namestringrequired
• slugstringrequired
• kindstringrequired

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | nullrequired
• domainsarrayrequired
• Each itemstring
• descriptionstringrequired
• contextobjectrequired
• Additional propertyAny value
• brandobjectrequired
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstringrequired

  enum: "active", "archived"

• is_defaultbooleanrequired
• route_readybooleanrequired
• setuparrayrequired
• Each itemobject
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request PATCH --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products/{productId}' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "example",
  "kind": "product",
  "website_url": "example",
  "description": "example",
  "context": {},
  "brand": {
    "company_name": "example",
    "logo_url": "example",
    "wordmark_url": "example",
    "website_url": "example",
    "primary_color": "example",
    "accent_color": "example",
    "background_color": "example",
    "surface_color": "example",
    "text_color": "example",
    "muted_text_color": "example",
    "heading_font_family": "example",
    "body_font_family": "example",
    "tone": "example",
    "footer_address": "example",
    "email_style": "example"
  },
  "status": "active"
}'

Update a product setup item

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring

  default: "person" · enum: "system", "person", "agent"

• notestring

  maxLength: 1000

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

curl example

curl --request PUT --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products/{productId}/setup/{key}' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "status": "todo",
  "completion_source": "person",
  "note": "example"
}'

Associate a domain with a product

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• domainstringrequired

  minLength: 3 · maxLength: 253

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• namestringrequired
• slugstringrequired
• kindstringrequired

  enum: "product", "store", "brand", "newsletter", "company", "other"

• website_urlstring | nullrequired
• domainsarrayrequired
• Each itemstring
• descriptionstringrequired
• contextobjectrequired
• Additional propertyAny value
• brandobjectrequired
• company_namestring

  maxLength: 160

• logo_urlstring

  maxLength: 2000

• wordmark_urlstring

  maxLength: 2000

• website_urlstring

  maxLength: 2000

• primary_colorstring

  maxLength: 7

• accent_colorstring

  maxLength: 7

• background_colorstring

  maxLength: 7

• surface_colorstring

  maxLength: 7

• text_colorstring

  maxLength: 7

• muted_text_colorstring

  maxLength: 7

• heading_font_familystring

  maxLength: 200

• body_font_familystring

  maxLength: 200

• tonestring

  maxLength: 1000

• footer_addressstring

  maxLength: 500

• email_stylestring

  maxLength: 20

• statusstringrequired

  enum: "active", "archived"

• is_defaultbooleanrequired
• route_readybooleanrequired
• setuparrayrequired
• Each itemobject
• keystringrequired

  enum: "context", "domain", "mailboxes", "journeys", "broadcasts", "compliance"

• statusstringrequired

  enum: "todo", "in_progress", "complete", "not_relevant"

• completion_sourcestring | nullrequired

  enum: "system", "person", "agent", null

• notestringrequired
• updated_atstring | nullrequired

  format: "date-time"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/products/{productId}/domains' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "domain": "example"
}'

listMailboxes

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Mailboxes visible to the actor.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• product_idstring | null

  The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.

  format: "uuid"

• domain_idstring | null

  format: "uuid"

• addressstringrequired

  format: "email"

• display_namestringrequired
• providerstringrequired

  enum: "gmail", "smtp"

• statusstringrequired

  enum: "pending", "active", "suspended", "reconnect_required", "disabled"

• status_reasonstring | null
• suspended_atstring | null
• mailbox_kindstringrequired

  enum: "domain", "starter"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Create a Banger-native work mailbox on a workspace sending domain.

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• domain_idstringrequired

  format: "uuid"

• local_partstringrequired

  minLength: 1 · maxLength: 64

• display_namestring

  maxLength: 200

Success response 200

Idempotent replay of a native mailbox creation.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• product_idstring | null

  The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.

  format: "uuid"

• domain_idstring | null

  format: "uuid"

• addressstringrequired

  format: "email"

• display_namestringrequired
• providerstringrequired

  enum: "gmail", "smtp"

• statusstringrequired

  enum: "pending", "active", "suspended", "reconnect_required", "disabled"

• status_reasonstring | null
• suspended_atstring | null
• mailbox_kindstringrequired

  enum: "domain", "starter"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Idempotency-Key: examplexxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "domain_id": "00000000-0000-4000-8000-000000000001",
  "local_part": "example",
  "display_name": "example"
}'

Create a hosted mailbox restricted to same-product hosted inboxes and the workspace signup recipient.

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• create_newboolean

  Create an additional hosted mailbox instead of resuming the initial one.

• local_partstring

  Name before @bangermail.com. Without it the mailbox gets a word name such as quiet-maple-harbor.

  minLength: 3 · maxLength: 40

• display_namestring

  maxLength: 200

Success response 200

Idempotent replay of starter identity creation.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• product_idstring | null

  The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.

  format: "uuid"

• domain_idstring | null

  format: "uuid"

• addressstringrequired

  format: "email"

• display_namestringrequired
• providerstringrequired

  enum: "gmail", "smtp"

• statusstringrequired

  enum: "pending", "active", "suspended", "reconnect_required", "disabled"

• status_reasonstring | null
• suspended_atstring | null
• mailbox_kindstringrequired

  enum: "domain", "starter"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes/starter' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Idempotency-Key: examplexxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "create_new": true,
  "local_part": "example",
  "display_name": "example"
}'

Resume the sender-reputation pause holding one mailbox, under the self-serve resume rules of resumeSending.

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• acknowledge_recipient_complaintbooleanrequired

  const: true

• reasonstring

  Why sending is being restored; recorded in the audit log.

  maxLength: 500

Success response 200

Mailbox reactivated, or already active after a prior successful request.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• workspace_idstringrequired

  format: "uuid"

• product_idstring | null

  The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.

  format: "uuid"

• domain_idstring | null

  format: "uuid"

• addressstringrequired

  format: "email"

• display_namestringrequired
• providerstringrequired

  enum: "gmail", "smtp"

• statusstringrequired

  enum: "pending", "active", "suspended", "reconnect_required", "disabled"

• status_reasonstring | null
• suspended_atstring | null
• mailbox_kindstringrequired

  enum: "domain", "starter"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes/{mailboxId}/reactivate' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "acknowledge_recipient_complaint": true,
  "reason": "example"
}'

listDrafts

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring | nullrequired

  format: "uuid"

• versionintegerrequired
• toarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• ccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• bccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• subjectstringrequired
• body_textstringrequired
• statusstringrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• attachmentsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• filenamestringrequired
• content_typestringrequired
• size_bytesintegerrequired
• sha256string
• created_atstring

  format: "date-time"

• body_html_urlstring

  format: "uri"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts?mailbox_id=00000000-0000-4000-8000-000000000001' \
  --header "Authorization: Bearer $BANGER_API_KEY"

createDraft

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring

  format: "uuid"

• toarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• ccarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• bccarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• subjectstring

  maxLength: 10000

• body_textstring

  maxLength: 2000000

• body_htmlstring

  maxLength: 2000000

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring | nullrequired

  format: "uuid"

• versionintegerrequired
• toarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• ccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• bccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• subjectstringrequired
• body_textstringrequired
• statusstringrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• attachmentsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• filenamestringrequired
• content_typestringrequired
• size_bytesintegerrequired
• sha256string
• created_atstring

  format: "date-time"

• body_html_urlstring

  format: "uri"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "mailbox_id": "00000000-0000-4000-8000-000000000001",
  "thread_id": "00000000-0000-4000-8000-000000000001",
  "to": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "cc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "bcc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "subject": "example",
  "body_text": "example",
  "body_html": "example"
}'

getDraft

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Canonical deliverability performance, health, and incidents.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring | nullrequired

  format: "uuid"

• versionintegerrequired
• toarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• ccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• bccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• subjectstringrequired
• body_textstringrequired
• statusstringrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• attachmentsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• filenamestringrequired
• content_typestringrequired
• size_bytesintegerrequired
• sha256string
• created_atstring

  format: "date-time"

• body_html_urlstring

  format: "uri"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

updateDraft

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueunspecified
• allOf 1object

  No additional properties

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring

  format: "uuid"

• toarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• ccarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• bccarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• subjectstring

  maxLength: 10000

• body_textstring

  maxLength: 2000000

• body_htmlstring

  maxLength: 2000000

• allOf 2object
• versionintegerrequired

  minimum: 1

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• thread_idstring | nullrequired

  format: "uuid"

• versionintegerrequired
• toarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• ccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• bccarrayrequired
• Each itemobject
• emailstringrequired
• namestring
• subjectstringrequired
• body_textstringrequired
• statusstringrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• attachmentsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• filenamestringrequired
• content_typestringrequired
• size_bytesintegerrequired
• sha256string
• created_atstring

  format: "date-time"

• body_html_urlstring

  format: "uri"

curl example

curl --request PUT --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "mailbox_id": "00000000-0000-4000-8000-000000000001",
  "thread_id": "00000000-0000-4000-8000-000000000001",
  "to": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "cc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "bcc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "subject": "example",
  "body_text": "example",
  "body_html": "example",
  "version": 1
}'

deleteDraft

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 204

Draft and referenced objects scheduled for deletion.

No response body.

curl example

curl --request DELETE --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

sendDraft

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 202

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• typestringrequired
• statusstringrequired

  enum: "accepted", "executing", "succeeded", "failed"

• workspace_revisionintegerrequired

  format: "int64"

• created_atstringrequired

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}/send' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Idempotency-Key: examplexxxxxxxxx'

uploadDraftAttachment

Authentication: Bearer workspace API key.

Parameters

Request body required

application/octet-stream

• valuestring

  format: "binary" · maxLength: 26214400

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• filenamestringrequired
• content_typestringrequired
• size_bytesintegerrequired
• sha256string
• created_atstring

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}/attachments' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'X-Banger-Filename: example' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @request-body

deleteDraftAttachment

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 204

Attachment scheduled for version-aware B2 deletion.

No response body.

curl example

curl --request DELETE --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}/attachments/{attachmentId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Read a draft HTML body

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Draft HTML.

text/html

• valuestring

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/drafts/{draftId}/html' \
  --header "Authorization: Bearer $BANGER_API_KEY"

listSendIntents

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Recent canonical sends and their provider state.

application/json

• valueobject
• dataarrayrequired
• Each itemobject

  No additional properties

• idstringrequired

  format: "uuid"

• statusstringrequired

  enum: "accepted", "scheduled", "queued", "executing", "partially_succeeded", "succeeded", "failed", "canceled"

• traffic_classstringrequired

  enum: "mailbox", "product", "broadcast"

• recipient_countintegerrequired

  minimum: 1

• provider_keystringrequired
• provider_statestringrequired

  enum: "pending", "leased", "submitted", "accepted", "ambiguous", "reconciling", "succeeded", "failed", "canceled"

• provider_message_idstring | null
• error_codestring | null
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• completed_atstring | null

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/send-intents?limit=50' \
  --header "Authorization: Bearer $BANGER_API_KEY"

getSendIntent

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Canonical asynchronous send status.

application/json

• valueobject
• dataobjectrequired

  No additional properties

• idstringrequired

  format: "uuid"

• statusstringrequired

  enum: "accepted", "scheduled", "queued", "executing", "partially_succeeded", "succeeded", "failed", "canceled"

• traffic_classstringrequired

  enum: "mailbox", "product", "broadcast"

• recipient_countintegerrequired

  minimum: 1

• provider_keystringrequired
• provider_statestringrequired

  enum: "pending", "leased", "submitted", "accepted", "ambiguous", "reconciling", "succeeded", "failed", "canceled"

• provider_message_idstring | null
• error_codestring | null
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• completed_atstring | null

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/send-intents/{sendIntentId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

listTransactionalSends

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• mailbox_idstring | nullrequired

  format: "uuid"

• command_idstring | nullrequired

  format: "uuid"

• statusstringrequired
• command_statusstring | nullrequired
• subjectstring
• recipientsarray
• Each itemobject
• emailstringrequired
• namestring
• recipient_countintegerrequired
• error_codestring | null
• send_intent_idstring

  format: "uuid"

• providerstring | null
• route_kindstring | null
• sourcestring
• from_addressstring
• recipient_statesobject
• Additional propertyinteger
• provider_message_idstring | null
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• completed_atstring | nullrequired

  format: "date-time"

• template_idstring | null

  format: "uuid"

• template_versioninteger | null
• workspace_revisioninteger | null
• command_resultobject
• Additional propertyAny value
• command_started_atstring | null

  format: "date-time"

• command_completed_atstring | null

  format: "date-time"

• body_textstring
• body_htmlstring
• reply_toarray
• Each itemobject
• emailstringrequired
• namestring
• headersobject
• Additional propertystring
• tagsarray
• Each itemobject
• namestringrequired
• valuestringrequired

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends?limit=200' \
  --header "Authorization: Bearer $BANGER_API_KEY"

createTransactionalSend

One recipient per Journey send. The To field accepts one email string or a one-element array of email strings/participant objects; Cc and Bcc must be empty. A new API Journey defaults to managed source content; legacy code Journeys retain complete-content sends.

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• mailbox_idstringrequired

  format: "uuid"

• tounspecifiedrequired
• oneOf 1string

  format: "email"

• oneOf 2array

  minItems: 1 · maxItems: 1

• Each itemunspecified
• oneOf 1string

  format: "email"

• oneOf 2object
• namestring
• emailstringrequired

  format: "email"

• ccarray

  maxItems: 0

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• bccarray

  maxItems: 0

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• subjectstring

  maxLength: 10000

• expires_atstring

  Discard a deferred Journey send after this instant; at most seven days from the original request.

  format: "date-time"

• expires_after_secondsinteger

  minimum: 1 · maximum: 604800

• body_textstring

  maxLength: 2000000

• body_htmlstring

  maxLength: 2000000

• reply_toarray

  maxItems: 500

• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• headersobject
• Additional propertystring

  maxLength: 5000

• tagsarray

  maxItems: 49

• Each itemobject

  No additional properties

• namestringrequired

  minLength: 1 · maxLength: 256

• valuestringrequired

  minLength: 1 · maxLength: 256

Success response 202

Successful response.

application/json

• valueobject
• dataobjectrequired
• action_kindstringrequired

  enum: "transactional.send"

• idstring

  format: "uuid"

• send_intent_idstring

  format: "uuid"

• provider_attempt_idstring

  format: "uuid"

• statusstringrequired
• replayedboolean
• journeyunspecifiedrequired
• anyOf 1object
• journey_idstringrequired

  format: "uuid"

• enrollment_idstringrequired

  format: "uuid"

• step_idstringrequired

  format: "uuid"

• step_positionintegerrequired
• originstring

  enum: "journey"

• journey_identitystring
• anyOf 2null
• ignored_variablesarrayrequired
• Each itemstring
• scheduled_atstring

  format: "date-time"

• reasonstring
• communication_reservation_idstring

  format: "uuid"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Idempotency-Key: examplexxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "mailbox_id": "00000000-0000-4000-8000-000000000001",
  "to": "person@example.com",
  "cc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "bcc": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "subject": "example",
  "expires_at": "2026-01-01T00:00:00Z",
  "expires_after_seconds": 1,
  "body_text": "example",
  "body_html": "example",
  "reply_to": [
    {
      "name": "example",
      "email": "person@example.com"
    }
  ],
  "headers": {},
  "tags": [
    {
      "name": "example",
      "value": "example"
    }
  ]
}'

getTransactionalSend

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• mailbox_idstring | nullrequired

  format: "uuid"

• command_idstring | nullrequired

  format: "uuid"

• statusstringrequired
• command_statusstring | nullrequired
• subjectstring
• recipientsarray
• Each itemobject
• emailstringrequired
• namestring
• recipient_countintegerrequired
• error_codestring | null
• send_intent_idstring

  format: "uuid"

• providerstring | null
• route_kindstring | null
• sourcestring
• from_addressstring
• recipient_statesobject
• Additional propertyinteger
• provider_message_idstring | null
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• completed_atstring | nullrequired

  format: "date-time"

• template_idstring | null

  format: "uuid"

• template_versioninteger | null
• workspace_revisioninteger | null
• command_resultobject
• Additional propertyAny value
• command_started_atstring | null

  format: "date-time"

• command_completed_atstring | null

  format: "date-time"

• body_textstring
• body_htmlstring
• reply_toarray
• Each itemobject
• emailstringrequired
• namestring
• headersobject
• Additional propertystring
• tagsarray
• Each itemobject
• namestringrequired
• valuestringrequired

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends/{transactionalSendId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

listTransactionalSendTimeline

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Ordered acceptance, provider-attempt, and recipient-event timeline.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• occurred_atstringrequired

  format: "date-time"

• event_typestringrequired
• labelstringrequired
• providerstring | null
• recipient_domainstring | null
• error_codestring | null

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends/{transactionalSendId}/timeline' \
  --header "Authorization: Bearer $BANGER_API_KEY"

retryTransactionalSend

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 202

Successful response.

application/json

• valueobject
• dataobjectrequired
• action_kindstringrequired

  enum: "transactional.send"

• idstringrequired

  format: "uuid"

• send_intent_idstringrequired

  format: "uuid"

• provider_attempt_idstringrequired

  format: "uuid"

• statusstringrequired
• replayedbooleanrequired

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends/{transactionalSendId}/retry' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Idempotency-Key: examplexxxxxxxxx'

listThreads

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Keyset-paginated workspace threads.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• subjectstringrequired
• snippetstringrequired
• last_message_atstringrequired

  format: "date-time"

• message_countintegerrequired
• unread_countintegerrequired
• is_archivedbooleanrequired
• is_trashbooleanrequired
• is_spambooleanrequired
• is_starredbooleanrequired
• is_sentbooleanrequired
• has_attachmentsbooleanrequired
• labelsarrayrequired
• Each itemstring
• participantsarray
• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• pageobjectrequired
• next_cursorstring
• has_morebooleanrequired

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/threads?cursor=example&limit=50&mailbox_id=00000000-0000-4000-8000-000000000001&label_id=00000000-0000-4000-8000-000000000001&view=inbox' \
  --header "Authorization: Bearer $BANGER_API_KEY"

getThread

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Thread and ordered messages.

application/json

• valueobject
• dataunspecifiedrequired
• allOf 1object
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• subjectstringrequired
• snippetstringrequired
• last_message_atstringrequired

  format: "date-time"

• message_countintegerrequired
• unread_countintegerrequired
• is_archivedbooleanrequired
• is_trashbooleanrequired
• is_spambooleanrequired
• is_starredbooleanrequired
• is_sentbooleanrequired
• has_attachmentsbooleanrequired
• labelsarrayrequired
• Each itemstring
• participantsarray
• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• allOf 2object
• messagesarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• thread_idstringrequired

  format: "uuid"

• sent_atstringrequired

  format: "date-time"

• fromobjectrequired
• namestring

  Further nesting omitted

• emailstringrequired

  format: "email"

  Further nesting omitted

• toarrayrequired
• Each itemobject

  Further nesting omitted

• ccarray
• Each itemobject

  Further nesting omitted

• body_textstring
• body_html_urlstring

  format: "uri"

• reply_originobject
• send_intent_idstringrequired

  format: "uuid"

  Further nesting omitted

• sourcestringrequired

  enum: "gateway", "transactional", "marketing", "mailbox", "agent"

  Further nesting omitted

• source_idstring

  format: "uuid"

  Further nesting omitted

• traffic_classstringrequired

  enum: "transactional", "marketing", "mailbox"

  Further nesting omitted

• kindstringrequired

  enum: "campaign", "sequence", "transactional", "mailbox", "agent"

  Further nesting omitted

• namestring

  Further nesting omitted

• has_attachmentsbooleanrequired
• attachmentsarray
• Each itemobject

  Further nesting omitted

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/threads/{threadId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

getMessageHtml

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Authenticated, sandbox-constrained HTML message body.

text/html

• valuestring

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/messages/{messageId}/html' \
  --header "Authorization: Bearer $BANGER_API_KEY"

downloadAttachment

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Authenticated attachment stream.

application/octet-stream

• valuestring

  format: "binary"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/attachments/{attachmentId}/content' \
  --header "Authorization: Bearer $BANGER_API_KEY"

searchMail

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Workspace-wide search results.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• mailbox_idstringrequired

  format: "uuid"

• subjectstringrequired
• snippetstringrequired
• last_message_atstringrequired

  format: "date-time"

• message_countintegerrequired
• unread_countintegerrequired
• is_archivedbooleanrequired
• is_trashbooleanrequired
• is_spambooleanrequired
• is_starredbooleanrequired
• is_sentbooleanrequired
• has_attachmentsbooleanrequired
• labelsarrayrequired
• Each itemstring
• participantsarray
• Each itemobject
• namestring
• emailstringrequired

  format: "email"

• pageobjectrequired
• next_cursorstring
• has_morebooleanrequired

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/search?q=example&cursor=example&limit=50&mailbox_id=00000000-0000-4000-8000-000000000001' \
  --header "Authorization: Bearer $BANGER_API_KEY"

listContacts

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• emailstringrequired

  format: "email"

• display_namestring | nullrequired
• attributesobjectrequired
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• pageobjectrequired
• next_cursorstring
• has_morebooleanrequired

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts?cursor=example&limit=50&q=example' \
  --header "Authorization: Bearer $BANGER_API_KEY"

upsertContact

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• emailstringrequired

  format: "email"

• display_namestring

  maxLength: 1000

• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• attributesobject
• Additional propertyAny value
• consent_confirmedboolean

  Required when newly subscribing an address.

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• emailstringrequired

  format: "email"

• display_namestring | nullrequired
• attributesobjectrequired
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "email": "person@example.com",
  "display_name": "example",
  "status": "subscribed",
  "attributes": {},
  "consent_confirmed": true
}'

getContact

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• emailstringrequired

  format: "email"

• display_namestring | nullrequired
• attributesobjectrequired
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• suppressedbooleanrequired
• suppression_reasonstring | nullrequired
• sourcesarrayrequired
• Each itemobject
• kindstringrequired
• referencestringrequired
• connection_idstring | nullrequired

  format: "uuid"

• metadataobjectrequired
• Additional propertyAny value
• first_seen_atstringrequired

  format: "date-time"

• last_seen_atstringrequired

  format: "date-time"

• listsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• namestringrequired
• subscription_statusstringrequired
• consent_evidencearrayrequired
• Each itemobject
• kindstringrequired
• referencestringrequired
• connection_idstring | nullrequired

  format: "uuid"

• metadataobjectrequired
• Additional propertyAny value
• first_seen_atstringrequired

  format: "date-time"

• last_seen_atstringrequired

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/{contactId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

deleteContact

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 204

Contact deleted.

No response body.

curl example

curl --request DELETE --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/{contactId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

listContactImports

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstring

  format: "uuid"

• filenamestring
• list_idstring | null

  format: "uuid"

• list_namestring | null
• statusstring
• total_rowsinteger
• imported_rowsinteger
• invalid_rowsinteger
• error_summaryarray
• Each itemstring
• consent_confirmedboolean
• consent_confirmed_atstring | null

  format: "date-time"

• processed_rowsinteger
• attempt_countinteger
• last_error_codestring | null
• created_atstring

  format: "date-time"

• completed_atstring | null

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/imports' \
  --header "Authorization: Bearer $BANGER_API_KEY"

importContacts

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• filenamestringrequired

  minLength: 1 · maxLength: 500

• list_idstring

  format: "uuid"

• consent_confirmedboolean

  Required when any imported row is subscribed.

• rowsarrayrequired

  minItems: 1 · maxItems: 5000

• Each itemobject
• emailstringrequired

  format: "email"

• display_namestring

  maxLength: 1000

• statusstring

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• attributesobject
• Additional propertyAny value

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• statusstringrequired

  enum: "queued"

• total_rowsintegerrequired
• imported_rowsintegerrequired
• invalid_rowsintegerrequired
• list_idstring | nullrequired

  format: "uuid"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/imports' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "filename": "example",
  "list_id": "00000000-0000-4000-8000-000000000001",
  "consent_confirmed": true,
  "rows": [
    {
      "email": "person@example.com",
      "display_name": "example",
      "status": "subscribed",
      "attributes": {}
    }
  ]
}'

upsertProductContact

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• emailstringrequired

  format: "email" · maxLength: 320

• display_namestring

  minLength: 0 · maxLength: 1000

• attributesobject
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• consent_evidenceobject

  No additional properties

• sourcestring

  minLength: 1 · maxLength: 2000

• referencestring

  minLength: 1 · maxLength: 2000

• observed_atstring

  format: "date-time"

• statementstring

  minLength: 1 · maxLength: 2000

• consent_confirmedboolean

Success response 200

Canonical read-back or idempotent receipt. Provider acceptance is sent; delivered requires a delivery event and does not prove inbox placement.

application/json

• valueobject
• dataunspecifiedrequired
• allOf 1object
• idstringrequired

  format: "uuid"

• emailstringrequired

  format: "email"

• display_namestring | nullrequired
• attributesobjectrequired
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• suppressedbooleanrequired
• suppression_reasonstring | nullrequired
• sourcesarrayrequired
• Each itemobject
• kindstringrequired
• referencestringrequired
• connection_idstring | nullrequired

  format: "uuid"

• metadataobjectrequired
• Additional propertyAny value
• first_seen_atstringrequired

  format: "date-time"

• last_seen_atstringrequired

  format: "date-time"

• listsarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• namestringrequired
• subscription_statusstringrequired
• consent_evidencearrayrequired
• Each itemobject
• kindstringrequired
• referencestringrequired
• connection_idstring | nullrequired

  format: "uuid"

• metadataobjectrequired
• Additional propertyAny value
• first_seen_atstringrequired

  format: "date-time"

• last_seen_atstringrequired

  format: "date-time"

• allOf 2object
• replayedbooleanrequired

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/upsert' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'X-Banger-Product-Id: 00000000-0000-4000-8000-000000000001' \
  --header 'Idempotency-Key: example' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "email": "person@example.com",
  "display_name": "example",
  "attributes": {},
  "status": "subscribed",
  "consent_evidence": {
    "source": "example",
    "reference": "example",
    "observed_at": "2026-01-01T00:00:00Z",
    "statement": "example"
  },
  "consent_confirmed": true
}'

validateProductContactImport

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject

  No additional properties

• rowsarrayrequired

  minItems: 1 · maxItems: 5000

• Each itemobject

  No additional properties

• emailstringrequired

  format: "email" · maxLength: 320

• display_namestring

  minLength: 0 · maxLength: 1000

• attributesobject
• Additional propertyAny value
• statusstringrequired

  enum: "subscribed", "unsubscribed", "bounced", "complained"

• consent_evidenceobject

  No additional properties

• sourcestring

  minLength: 1 · maxLength: 2000

• referencestring

  minLength: 1 · maxLength: 2000

• observed_atstring

  format: "date-time"

• statementstring

  minLength: 1 · maxLength: 2000

• consent_confirmedboolean

Success response 200

Canonical read-back or idempotent receipt. Provider acceptance is sent; delivered requires a delivery event and does not prove inbox placement.

application/json

• valueobject
• dataobjectrequired
• validbooleanrequired
• total_rowsintegerrequired
• valid_rowsintegerrequired
• errorsarrayrequired
• Each itemobject
• rowintegerrequired
• codestringrequired
• messagestringrequired

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/import-validation' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'X-Banger-Product-Id: 00000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "rows": [
    {
      "email": "person@example.com",
      "display_name": "example",
      "attributes": {},
      "status": "subscribed",
      "consent_evidence": {
        "source": "example",
        "reference": "example",
        "observed_at": "2026-01-01T00:00:00Z",
        "statement": "example"
      }
    }
  ],
  "consent_confirmed": true
}'

getProductContactImport

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Canonical read-back or idempotent receipt. Provider acceptance is sent; delivered requires a delivery event and does not prove inbox placement.

application/json

• valueobject
• dataobjectrequired
• idstring

  format: "uuid"

• filenamestring
• list_idstring | null

  format: "uuid"

• list_namestring | null
• statusstring
• total_rowsinteger
• imported_rowsinteger
• invalid_rowsinteger
• error_summaryarray
• Each itemstring
• consent_confirmedboolean
• consent_confirmed_atstring | null

  format: "date-time"

• processed_rowsinteger
• attempt_countinteger
• last_error_codestring | null
• created_atstring

  format: "date-time"

• completed_atstring | null

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/imports/{importId}' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'X-Banger-Product-Id: 00000000-0000-4000-8000-000000000001'

List stored contact attribute keys

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemstring

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/fields' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Propose contact import column mappings

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• filenamestring

  maxLength: 500

• columnsarrayrequired

  minItems: 1 · maxItems: 100

• Each itemobject
• namestringrequired

  minLength: 1 · maxLength: 200

• samplesarray

  maxItems: 8

• Each itemstring

  maxLength: 120

• filledinteger

  minimum: 0

• rowsinteger

  minimum: 0

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• mappingobjectrequired
• columnsarrayrequired
• Each itemobject
• columnstringrequired
• targetstringrequired

  enum: "email", "display_name", "first_name", "last_name", "locale", "time_zone", "status", "unsubscribed_flag", "subscribed_flag", "field", "ignore"

• field_keystring
• field_typestring

  enum: "text", "number", "boolean", "date", "choice", "choices"

• confidencenumberrequired
• sourcestringrequired

  enum: "saved", "ai", "rules", "person"

• alternativesarray
• Each itemobject

  Further nesting omitted

• locale_valuesobjectrequired
• Additional propertystring | null
• reviewobjectrequired
• neededbooleanrequired
• reasonsarrayrequired
• Each itemstring
• columnsarrayrequired
• Each itemstring
• sourcestringrequired

  enum: "saved", "ai", "rules"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contacts/import-mapping' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "filename": "example",
  "columns": [
    {
      "name": "example",
      "samples": [
        "example"
      ],
      "filled": 0,
      "rows": 0
    }
  ]
}'

listContactLists

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• namestringrequired
• descriptionstringrequired
• member_countintegerrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-lists' \
  --header "Authorization: Bearer $BANGER_API_KEY"

createContactList

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• namestringrequired

  minLength: 1 · maxLength: 200

• descriptionstring

  maxLength: 2000

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• namestringrequired
• descriptionstringrequired
• member_countintegerrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-lists' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "example",
  "description": "example"
}'

getContactList

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataobjectrequired
• idstringrequired

  format: "uuid"

• namestringrequired
• descriptionstringrequired
• created_atstringrequired

  format: "date-time"

• updated_atstringrequired

  format: "date-time"

• membersarrayrequired
• Each itemobject
• idstringrequired

  format: "uuid"

• emailstringrequired
• display_namestring | nullrequired
• statusstringrequired
• attributesobjectrequired
• Additional propertyAny value
• updated_atstringrequired

  format: "date-time"

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-lists/{listId}' \
  --header "Authorization: Bearer $BANGER_API_KEY"

addContactListMembers

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• contact_idsarrayrequired

  maxItems: 1000

• Each itemstring

  format: "uuid"

Success response 204

List membership updated.

No response body.

curl example

curl --request POST --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-lists/{listId}/members' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "contact_ids": [
    "00000000-0000-4000-8000-000000000001"
  ]
}'

removeContactListMembers

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• contact_idsarrayrequired

  maxItems: 1000

• Each itemstring

  format: "uuid"

Success response 204

List membership updated.

No response body.

curl example

curl --request DELETE --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-lists/{listId}/members' \
  --header "Authorization: Bearer $BANGER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "contact_ids": [
    "00000000-0000-4000-8000-000000000001"
  ]
}'

The product's contact fields (built-in, declared and discovered) with type, choices, source, how many contacts have a value, and the segment operators each supports.

Authentication: Bearer workspace API key.

Parameters

Request body

No request body is specified in the contract.

Success response 200

Successful response.

application/json

• valueobject
• dataarrayrequired
• Each itemobject
• keystringrequired

  pattern: "^[a-z][a-z0-9_]{0,39}$"

• labelstringrequired

  maxLength: 80

• descriptionstringrequired

  maxLength: 500

• typestringrequired

  enum: "text", "number", "boolean", "date", "choice", "choices"

• optionsarrayrequired

  maxItems: 50

• Each itemstring
• originstringrequired

  enum: "system", "person", "agent", "form", "import", "api", "event", "discovered"

• statusstringrequired

  enum: "active", "hidden"

• created_atstring

  format: "date-time"

• updated_atstring

  format: "date-time"

• operatorsarray
• Each itemstring
• contacts_with_valueinteger

curl example

curl --request GET --globoff 'https://api.bangermail.com/v1/workspaces/{workspaceId}/contact-fields' \
  --header "Authorization: Bearer $BANGER_API_KEY"

Declare a contact field: label, type (text, number, boolean, date, choice, choices), optional key, options and description.

Authentication: Bearer workspace API key.

Parameters

Request body required

application/json

• valueobject
• keystring

  pattern: "^[a-z][a-z0-9_]{0,39}$"

• labelstringrequired

  minLength: 1 · maxLength: 80

• descriptionstring

  maxLength: 500

• typestring

  default: "text" · enum: "text", "number", "boolean", "date", "choice", "choices"

• optionsarray

  maxItems: 50

• Each itemstring

Success response 201

Successful response.

application/json

• valueobject
• dataobjectrequired
• keystringrequired

  pattern: "^[a-z][a-z0-9_]{0,39}$"

• labelstringrequired

  maxLength: 80

• descriptionstringrequired

  maxLength: 500

• typestringrequired

  enum: "text", "number", "boolean", "date", "choice", "choices"

• optionsarrayrequired

  maxItems: 50

• Each itemstring
• originstringrequired

  enum: "system", "person", "agent", "form", "import", "api", "event", "discovered"

• statusstringrequired

  enum: "active", "hidden"

• created_atstring

  format: "date-time"

• updated_atstring

  format: "date-time"

• operatorsarray
• Each itemstring
• contacts_with_valueinteger