Lists

A list holds recipients. Campaigns reference an existing list or create one implicitly. See Lists & recipients for the field-schema model.

List all lists

GET/api/v1/lists

requires lists:read

Requires lists:read. Not paginated — it returns every list in the account, newest first, each with its recipient count.

cURL

curl -H "x-api-key: drse_your_api_key" \
  https://api.utskick.dr.se/api/v1/lists

TypeScript

const res = await fetch("https://api.utskick.dr.se/api/v1/lists", {
  headers: { "x-api-key": process.env.DRSE_API_KEY! },
});
const { data, meta } = await res.json();
console.log(`${meta.listCount} lists, ${meta.totalRecipientCount} recipients`);

200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Summer list",
      "createdAt": "2026-07-25T09:00:00.000Z",
      "updatedAt": "2026-07-25T09:30:00.000Z",
      "recipientCount": 250
    }
  ],
  "meta": { "totalRecipientCount": 250, "listCount": 1 }
}

Note the meta shape differs from the cursor-paginated endpoints: there are no cursors, because there are no pages.

Field	Notes
recipientCount	Live count of recipients in this list
meta.totalRecipientCount	Recipients across the whole account, not just these lists
meta.listCount	Number of lists returned

Failures

Status	code	When
401	unauthorized	Key problem
403	forbidden	Key lacks lists:read

Create a list

POST/api/v1/lists

requires lists:create

Requires lists:create. Creates an empty list with an unlocked field schema.

Body

Field	Type	Required	Notes
name	string	yes	1–200 characters

cURL

curl -X POST https://api.utskick.dr.se/api/v1/lists \
  -H "x-api-key: drse_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer list" }'

TypeScript

const res = await fetch("https://api.utskick.dr.se/api/v1/lists", {
  method: "POST",
  headers: {
    "x-api-key": process.env.DRSE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Summer list" }),
});
const { data } = await res.json();
console.log(data.id);

201 Created

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Summer list",
    "userId": "user_2abc",
    "schemaLockedAt": null,
    "lastActivityAt": "2026-07-25T09:00:00.000Z",
    "createdAt": "2026-07-25T09:00:00.000Z",
    "updatedAt": "2026-07-25T09:00:00.000Z"
  }
}

Field	Notes
userId	The account owning the list. Returned but not useful to API consumers
schemaLockedAt	null until the first recipient is added, which locks the custom-field schema
lastActivityAt	Drives retention: an untouched list is deleted after 90 days of inactivity

Failures

Status	code	When
400	validation_failed	name empty or over 200 characters
401	unauthorized	Key problem
403	forbidden	Key lacks lists:create

Retrieve a list's field schema

GET/api/v1/lists/:listId/schema

requires lists:read

Requires lists:read. Tells you which custom fields this list accepts — call it before importing into an existing list so your column mapping matches.

cURL

curl -H "x-api-key: drse_your_api_key" \
  https://api.utskick.dr.se/api/v1/lists/550e8400-e29b-41d4-a716-446655440001/schema

TypeScript

const listId = "550e8400-e29b-41d4-a716-446655440001";
const res = await fetch(
  `https://api.utskick.dr.se/api/v1/lists/${listId}/schema`,
  { headers: { "x-api-key": process.env.DRSE_API_KEY! } },
);
const { data } = await res.json();
if (data.status === "locked") {
  console.log(data.fields.map((f) => f.fieldKey));
}

200 OK — an empty list whose schema has not been locked yet:

{ "data": { "status": "unlocked", "fields": [] } }

Once the first recipient has been added the schema is frozen:

{
  "data": {
    "status": "locked",
    "fields": [
      {
        "fieldKey": "vip",
        "fieldLabel": "VIP",
        "defaultValue": null,
        "missingBehavior": "skip"
      }
    ]
  }
}

Field	Notes
status	unlocked = no recipients yet, the first add defines the schema. locked = frozen; every later add must conform
fields[].fieldKey	Alphanumeric + underscore, ≤64 characters
fields[].defaultValue	Substituted when a row omits the field. null means no default
fields[].missingBehavior	skip = drop rows missing this field, fail = reject the import. Only consulted when defaultValue is null

Failures

Status	code	When
400	validation_failed	listId is not a UUID (List ID must be a valid UUID)
401	unauthorized	Key problem
403	forbidden	Key lacks lists:read
404	not_found	List not found — unknown id, or a list in another account