The Imports API from Buttondown — 5 operation(s) covering bulk subscriber imports — the supported path for adding subscribers at volume.
openapi: 3.1.0
info:
title: Buttondown Imports API
version: 1.0.0
description: The Buttondown API lets you manage newsletters, subscribers, emails, and more. See [the documentation](https://docs.buttondown.com/api-introduction)
for guides and examples.
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.buttondown.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Imports
paths:
/imports:
get:
operationId: list_imports
summary: List Imports
parameters:
- in: query
name: page
required: false
description: The page number of the paginated response.
schema:
type: integer
title: Page
description: The page number of the paginated response.
default: 1
example: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImportPage'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: Conflict
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: List all imports
tags:
- Imports
security:
- ApiKeyAuth: []
post:
operationId: create_import
summary: Create Import
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
links:
retrieve_import:
operationId: retrieve_import
parameters:
path.id: $response.body#/id
update_import:
operationId: update_import
parameters:
path.id: $response.body#/id
delete_import:
operationId: delete_import
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_CreateImportErrorCode_'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Create a new import by uploading a file
tags:
- Imports
requestBody:
content:
multipart/form-data:
schema:
properties:
file:
format: binary
title: File
type: string
metadata:
anyOf:
- type: string
- type: 'null'
title: Metadata
required:
- file
title: MultiPartBodyParams
type: object
required: true
security:
- ApiKeyAuth: []
/imports/{id}:
get:
operationId: retrieve_import
summary: Retrieve Import
parameters:
- in: path
name: id
schema:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub_imp)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
links:
update_import:
operationId: update_import
parameters:
path.id: $response.body#/id
delete_import:
operationId: delete_import
parameters:
path.id: $response.body#/id
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Retrieve a specific import by its ID
tags:
- Imports
security:
- ApiKeyAuth: []
patch:
operationId: update_import
summary: Update Import
parameters:
- in: path
name: id
schema:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub_imp)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
links:
retrieve_import:
operationId: retrieve_import
parameters:
path.id: $response.body#/id
delete_import:
operationId: delete_import
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'409':
description: Conflict
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Update an import's properties
tags:
- Imports
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateImportInput'
required: true
security:
- ApiKeyAuth: []
delete:
operationId: delete_import
summary: Delete Import
parameters:
- in: path
name: id
schema:
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub_imp)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
title: Id
type: string
required: true
responses:
'204':
description: No Content
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Delete an import
tags:
- Imports
security:
- ApiKeyAuth: []
components:
schemas:
CreateImportErrorCode:
enum:
- import_failure
- invalid_file_type
- malformed_csv
title: CreateImportErrorCode
type: string
description: An enumeration.
ErrorMessage:
properties:
code:
description: The error code.
title: Code
type: string
detail:
description: A human-readable description of the error.
title: Detail
type: string
metadata:
additionalProperties:
type: string
default: {}
description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
how to resolve it.
title: Metadata
type: object
required:
- detail
title: ErrorMessage
type: object
ErrorMessage_CreateImportErrorCode_:
properties:
code:
allOf:
- $ref: '#/components/schemas/CreateImportErrorCode'
description: The error code.
detail:
description: A human-readable description of the error.
title: Detail
type: string
metadata:
additionalProperties:
type: string
default: {}
description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
how to resolve it.
title: Metadata
type: object
required:
- detail
title: ErrorMessage[CreateImportErrorCode]
type: object
Import:
description: 'Imports let you bring data into Buttondown in bulk by uploading a file.
Currently, subscriber imports are supported.'
properties:
id:
description: A unique TypeID associated with the object.
title: Id
type: string
creation_date:
description: The date and time at which the object was first created.
format: date-time
title: Creation Date
type: string
type:
$ref: '#/components/schemas/ImportType'
description: The type of import.
status:
$ref: '#/components/schemas/ImportStatus'
description: The current status of the import.
source:
$ref: '#/components/schemas/ImportSource'
description: The detected source of the import file.
label:
anyOf:
- type: string
- type: 'null'
description: An optional label for the import.
title: Label
metadata:
additionalProperties: true
description: Metadata about the import, such as detected column mappings.
title: Metadata
type: object
results:
anyOf:
- $ref: '#/components/schemas/ImportResult'
- type: 'null'
description: The results of the import, available after completion.
required:
- id
- creation_date
- type
- status
- source
title: Import
type: object
ImportPage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/Import'
title: Results
type: array
next:
anyOf:
- type: string
- type: 'null'
description: The URL to the next page of results, if any.
title: Next
previous:
anyOf:
- type: string
- type: 'null'
description: The URL to the previous page of results, if any.
title: Previous
count:
description: The total number of results across all pages.
title: Count
type: integer
required:
- results
- count
title: Page[Import]
type: object
ImportResult:
properties:
new_subscribers:
anyOf:
- type: integer
- type: 'null'
description: The number of new subscribers created by the import.
title: New Subscribers
updated_subscribers:
anyOf:
- type: integer
- type: 'null'
description: The number of existing subscribers updated by the import.
title: Updated Subscribers
existing_subscribers:
anyOf:
- type: integer
- type: 'null'
description: The number of subscribers that already existed and were skipped.
title: Existing Subscribers
reason_to_bad_subscribers:
additionalProperties:
items:
type: string
type: array
description: A mapping of error reasons to the list of email addresses that failed for that reason.
title: Reason To Bad Subscribers
type: object
new_tags:
anyOf:
- type: integer
- type: 'null'
description: The number of new tags created by the import.
title: New Tags
title: ImportResult
type: object
ImportSource:
enum:
- bare
- beehiiv
- buttondown
- custom
- flodesk
- ghost
- google
- mailchimp
- mailerlite
- memberful
- pencilbooth
- sender_dot_net
- sendy
- shopify
- sparkloop
- squarespace
- standard
- substack
- tinyletter
title: ImportSource
type: string
description: An enumeration.
ImportStatus:
enum:
- failed
- in_progress
- not_started
- succeeded
- validating
title: ImportStatus
type: string
description: An enumeration.
ImportType:
enum:
- subscriber_import
title: ImportType
type: string
description: An enumeration.
UpdateImportInput:
additionalProperties: false
properties:
label:
anyOf:
- maxLength: 500
type: string
- type: 'null'
description: An optional label for the import.
title: Label
example: June 2025 migration
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: Metadata about the import, such as detected column mappings.
title: Metadata
example:
email_column: 0
metadata_columns:
name: 1
status:
anyOf:
- const: in_progress
type: string
- type: 'null'
description: The status of the import. Set to 'in_progress' to begin executing the import.
title: Status
example: in_progress
title: UpdateImportInput
type: object
ValidationErrorDetail:
properties:
type:
description: The type of validation error.
title: Type
type: string
loc:
description: The location of the error in the request.
items:
anyOf:
- type: string
- type: integer
title: Loc
type: array
msg:
description: A human-readable error message.
title: Msg
type: string
required:
- type
- loc
- msg
title: ValidationErrorDetail
type: object
ValidationErrorMessage:
properties:
detail:
description: A list of validation errors.
items:
$ref: '#/components/schemas/ValidationErrorDetail'
title: Detail
type: array
required:
- detail
title: ValidationErrorMessage
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key passed as 'Token <your-api-key>' in the Authorization header.