Buttondown logo

Updating an import

Sample requests

These sample requests are autogenerated by the OpenAPI spec. This endpoint requires one or more parameters in the URL: those are offset in curly-braces.

import requests

url = "https://api.buttondown.com/v1/imports/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "label": "June 2025 migration",
  "metadata": {
    "email_column": 0,
    "metadata_columns": {
      "name": 1
    }
  },
  "source": "custom",
  "status": "in_progress"
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "id": "sub_imp_0k28edc3fw896bp4mrhc535z5k",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "type": "subscriber_import",
    "status": "succeeded",
    "source": "substack",
    "label": "subscribers.csv",
    "metadata": {
        "email_column": 0,
        "metadata_columns": {}
    },
    "results": {
        "new_subscribers": 100,
        "updated_subscribers": null,
        "existing_subscribers": 20,
        "reason_to_bad_subscribers": {
            "That email address is invalid.": [
                "email@examplecom"
            ]
        },
        "new_tags": 2
    }
}

Body parameters

All parameters are optional unless explicitly specified.

labelstring

An optional label for the import.

example
"June 2025 migration"

metadataobject

Metadata about the import, such as detected column mappings.

example
{ "email_column": 0, "metadata_columns": { "name": 1 } }

sourcestring · enum

Override the detected source. Only allowed before the import starts; set to 'custom' to have the import read the column mappings in metadata instead of the detected source's own column knowledge.

example
"custom"
values
  • bare

    A single-column CSV containing only email addresses.

  • beehiiv

    A CSV exported from Beehiiv.

  • buttondown

    A CSV exported from Buttondown.

  • custom

    A CSV that requires manual column mapping.

  • flodesk

    A CSV exported from Flodesk.

  • ghost

    A CSV exported from Ghost.

  • google

    A CSV exported from Google.

  • mailchimp

    A CSV exported from Mailchimp.

  • mailerlite

    A CSV exported from MailerLite.

  • memberful

    A CSV exported from Memberful.

  • pencilbooth

    A CSV exported from Pencilbooth.

  • sender_dot_net

    A CSV exported from Sender.net.

  • sendy

    A CSV exported from Sendy.

  • shopify

    A CSV exported from Shopify.

  • sparkloop

    A CSV exported from SparkLoop.

  • squarespace

    A CSV exported from Squarespace.

  • standard

    A CSV with standard column names that was auto-mapped.

  • substack

    A CSV exported from Substack.

  • tinyletter

    A CSV exported from TinyLetter.

statusstring

The status of the import. Set to 'in_progress' to begin executing the import.

example
"in_progress"