List imports

Returns the org's imports, newest first, each with its report.

GET /v1/marketing/imports

Marketing → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/marketing/imports`
Method	`GET`
Operation	`get_marketing_imports`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns the org's imports, newest first, each with its report.

Request

2 fields.

Field	In	Type	Required	Description
`list`	query	string	—	List keeps one list's imports, by id or slug.
`limit`	query	integer	—	Limit is the page size, 50 by default and at most 200.

Response

Status	Body	Meaning
`200`	marketing.ImportPage	ok
`default`	problem-details	refused

200 body — 60 fields.

Field	In	Type	Always	Description
`data`	body	marketing.Import[]	—	Data is the page.
`data[].by`	body	string	—	By is who created it.
`data[].createdAt`	body	integer (int64)	—	CreatedAt, UpdatedAt and FinishedAt are unix seconds.
`data[].error`	body	string	—	Error is why a failed import stopped.
`data[].finishedAt`	body	integer (int64)	—	FinishedAt is when it ended; 0 while it runs.
`data[].id`	body	string	—	ID is the import's id ("imp_" and 96 random bits in hex): the batch every subscriber it adds records as its source ref.
`data[].list`	body	string	—	List is the list it fills.
`data[].options`	body	marketing.ImportOptions	—
`data[].options.basis`	body	string	—	Basis is the consent basis recorded for every row: explicit, legitimate_interest or unverified (the default).
`data[].options.dryRun`	body	boolean	—	DryRun reads and judges every row and writes nothing.
`data[].options.format`	body	string	—	Format is csv or json; ignored for a source.
`data[].options.from`	body	string	—	From is a source to read instead of a file, as the host offers them: commerce (the org's commerce form subscribers) or crm (the confirmations the retired newsletter filed in the org's CRM).
`data[].options.key`	body	string	—	Key makes creating the import idempotent: a second create with the same key answers the first import.
`data[].options.map`	body	marketing.Mapping	—
`data[].options.map.consentAt`	body	string	—	ConsentAt is a column holding when the person subscribed.
`data[].options.map.email`	body	string	—	Email is the column holding the address.
`data[].options.map.fields`	body	object	—	Fields maps a custom field key to the column holding it.
`data[].options.map.fields.*`	body	string	—
`data[].options.map.first`	body	string	—	First and Last are columns holding the name in two parts.
`data[].options.map.language`	body	string	—	Language is a column holding a language or locale.
`data[].options.map.last`	body	string	—	Last is the family name's column.
`data[].options.map.name`	body	string	—	Name is a column holding the whole name.
`data[].options.map.status`	body	string	—	Status is a column holding a status from another provider (subscribed, unsubscribed, cleaned, bounced, complained and their usual spellings).
`data[].options.map.tags`	body	string	—	Tags is a column of tags separated by commas or semicolons.
`data[].options.name`	body	string	—	Name is the file's name, for the record.
`data[].options.size`	body	integer (int64)	—	Size is the file's size in bytes, when known; the upload is refused past it.
`data[].options.status`	body	string	—	Status is what a new row becomes: subscribed (the default), unsubscribed, bounced, complained or cleaned, as an export from another provider records.
`data[].options.tags`	body	string[]	—	Tags are put on every row the import writes.
`data[].options.verify`	body	boolean	—	Verify checks each address deliverable before writing it.
`data[].parsed`	body	integer (int64)	—	Parsed is how many bytes of the file the worker has read and judged.
`data[].received`	body	integer (int64)	—	Received is how many bytes of the file have arrived; the next piece starts here.
`data[].report`	body	marketing.Report	—
`data[].report.bases`	body	object	—	Bases count the rows written by the consent basis recorded for them.
`data[].report.bases.*`	body	integer (int64)	—
`data[].report.columns`	body	string[]	—	Columns are the file's columns, as its header named them.
`data[].report.imported`	body	integer (int64)	—	Imported is how many rows became new subscribers.
`data[].report.invalid`	body	integer (int64)	—	Invalid is how many could not be read as an address, for the reasons in Reasons.
`data[].report.map`	body	marketing.Mapping	—
`data[].report.map.consentAt`	body	string	—	ConsentAt is a column holding when the person subscribed.
`data[].report.map.email`	body	string	—	Email is the column holding the address.
`data[].report.map.fields`	body	object	—	Fields maps a custom field key to the column holding it.
`data[].report.map.fields.*`	body	string	—
`data[].report.map.first`	body	string	—	First and Last are columns holding the name in two parts.
`data[].report.map.language`	body	string	—	Language is a column holding a language or locale.
`data[].report.map.last`	body	string	—	Last is the family name's column.
`data[].report.map.name`	body	string	—	Name is a column holding the whole name.
`data[].report.map.status`	body	string	—	Status is a column holding a status from another provider (subscribed, unsubscribed, cleaned, bounced, complained and their usual spellings).
`data[].report.map.tags`	body	string	—	Tags is a column of tags separated by commas or semicolons.
`data[].report.reasons`	body	object	—	Reasons count the skipped and invalid rows by why.
`data[].report.reasons.*`	body	integer (int64)	—
`data[].report.rows`	body	integer (int64)	—	Rows is how many rows were read.
`data[].report.samples`	body	marketing.Sample[]	—	Samples are the first rejected rows: their row number and the reason.
`data[].report.samples[].reason`	body	string	—	Reason is why it was rejected.
`data[].report.samples[].row`	body	integer (int64)	—	Row is the row's number in the file, the header not counted.
`data[].report.skipped`	body	integer (int64)	—	Skipped is how many were left as they were, for the reasons in Reasons.
`data[].report.statuses`	body	object	—	Statuses count the rows written by the status they were written with.
`data[].report.statuses.*`	body	integer (int64)	—
`data[].report.updated`	body	integer (int64)	—	Updated is how many were already on the list and gained a name, tags or fields, or a status that leaves the list.
`data[].state`	body	string	—	State is receiving (waiting for its bytes), queued, processing, done, failed or cancelled.
`data[].updatedAt`	body	integer (int64)	—	UpdatedAt is the last progress.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo marketing imports list

.ts

.py

.go

.rs

.java

import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getMarketingImports();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketingApi(client).get_marketing_imports()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.MarketingAPI.GetMarketingImports(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, marketing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = marketing_api::get_marketing_imports(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketingApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new MarketingApi(client).getMarketingImports();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/marketing/imports \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches marketing through the marketing tool, which names its 82 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_marketing_audiences"
         }
       }
     }'

Marketing API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousGet imports NextExport lists