Imports

Imports let you bring data into Buttondown in bulk by uploading a file. Currently, subscriber imports (via CSV) are supported.

1. Upload a CSV file to the create endpoint.
2. Buttondown auto-detects the source (Substack, Mailchimp, etc.) and maps columns accordingly. The detected source and the column it will read email addresses from come back on the import's source and metadata.
3. If the source can't be detected, you can provide a metadata field with explicit column mappings. You can also override a detected source by updating the import with source set to custom before starting it, in which case your metadata column mappings are used instead.
4. A single column of email addresses (no header needed) starts immediately. Anything else waits until you update the import with status set to in_progress.
5. The import processes asynchronously — poll the retrieve endpoint to check its status.

Buttondown can auto-detect CSVs exported from the following services:

• Beehiiv
• Buttondown
• Flodesk
• Ghost
• Google
• Mailchimp
• Mailerlite
• Memberful
• Pencilbooth
• Sender.net
• Sendy
• Shopify
• Sparkloop
• Squarespace
• Substack
• Tinyletter

If your CSV doesn't match a known source but every column has a standard name (like email, name, tags), Buttondown maps those columns automatically and reports the import's source as standard. Otherwise the source is custom and you pass explicit column mappings via the metadata field.

When providing metadata, use the following structure:

{
  "email_column": 0,
  "metadata_columns": {
    "name": 1,
    "company": 2
  }
}

• email_column: The zero-based index of the column containing email addresses.
• metadata_columns: A mapping of field names to their zero-based column indices.

Other optional keys, each a zero-based column index: creation_date_column, notes_column, tags_column, ip_address_column, referrer_url_column, unsubscription_date_column, unsubscription_reason_column, utm_source_column, utm_medium_column, and utm_campaign_column.

Rows whose creation date is in the future, whose email address is invalid, or which Buttondown's filtering rejects are listed under results.reason_to_bad_subscribers once the import completes.