Browse API reference

Update a mailing list

posthttps://api.intelliprint.net/v1/mailing_lists/{id}

Updates a mailing list.

You can add or replace recipients in bulk using this endpoint.

Parameters

Path

idrequired

string

The ID of the mailing list to update.

Request body

application/json

name

string

A user-friendly name for this mailing list. This name is displayed in the dashboard.

Example"Black Friday Leads"

delete_old_recipients

boolean

Whether to delete all the currently stored recipients from the mailing list.

Defaultfalse

Examplefalse

recipients

array of object

An optional list of new recipients to add to the mailing list.

Array of object.

addressobject

namestring

The name of the recipient.

Example"John Doe"

linestringrequired

The complete address line for the recipient.

Example"123 Main St, Anytown, Anyplace"

postcodestring

The postal code of the address.

Example"AB1 2CD"

countrystring

The country code of the address. This is an ISO 3166-1 alpha-2 country code. Example: GB.

Default"GB"

Example"GB"

variablesobject

An arbitrary object of the dynamic fields for this recipient. Dynamic fields are used to tailor templates uniquely for each recipient.

address_validation

object

Whether to request address validation for the mailing list. This is a value-added service that we offer to ensure your mailings are only charged for and sent to real, deliverable addresses. Please contact us at hello@intelliprint.net to enable this service for your account.

requestedboolean

Whether to perform address validation on all the recipients in the mailing list.

Defaultfalse

Examplefalse

Responses

Sample JSON for every response shape is in the right rail. Expand a row below to see every field this endpoint can return.

200Successful responseapplication/json

id

string

A globally unique identifier for the mailing list.

Example"mal_eg"

object

string

The object type. Always mailing_list.

Allowed valuesmailing_list

account

string

The Intelliprint account ID that the mailing list belongs to.

Example"acc_eg"

name

string

A user-friendly name for this mailing list. This name is displayed in the dashboard.

Example"Black Friday Leads"

recipients

integer

The number of recipients present in the mailing list. This value is updated automatically when recipients are added or removed from the mailing list.

Example1000

variables

array of object

An array of the dynamic fields present in the mailing list. Dynamic fields are used to tailor templates uniquely for each recipient.

Array of object.

namestring

The name of the dynamic field. This is the value without the curly braces. For example, if the dynamic field is {exampleA}, the name will be exampleA.

Example"salutation"

longest_address_line

string

This is the longest address line present across all recipients in the mailing list. We keep track of this to ensure the address box on postcard templates is large enough to fit the longest address.

Example"123 Main St, Anytown, Anyplace"

address_validation

object

Address validation is a value-added service that we offer to ensure your mailings are only charged for and sent to real, deliverable addresses. Please contact us at hello@intelliprint.net to enable this service for your account.

requestedboolean

Whether address validation has been requested for the mailing list.

Defaultfalse

Examplefalse

completedboolean

Whether all addresses in the mailing list have been validated.

Defaultfalse

Examplefalse

recipientsobject

The number of recipients that have passed or failed address validation.

passedinteger

The number of recipients that have passed address validation.

Default0

Example0

failedinteger

The number of recipients that have failed address validation.

Default0

Example0

created

integer<int64>

The UNIX timestamp of when the mailing list was created. We use UNIX timestamps to avoid timezone-based issues.

Example1761955200

400Example error responseapplication/json

error

object

messagestring

A human-readable message describing the error. You can display this to your users to help them understand what went wrong.

Example"Received unknown parameter: testmood (Did you mean testmode?)"

typestring

The general category of the error.

Allowed valuesinvalid_request_errorauthentication_errorpayment_errorrate_limitedinternal_error

Example"invalid_request_error"

codestring

A unique code for the specific error that occurred.

Allowed valuesparameter_invalidparameter_missingparameter_unknownbody_too_largebody_incorrect_formatno_api_keyinvalid_api_keylogged_outforbiddenpayment_errornot_foundrate_limitedrefusedinternal_error

Example"parameter_unknown"

paramstring

The parameter that caused the error, if applicable.

Example"testmood"

Request example

cURL

curl -X POST https://api.intelliprint.net/v1/mailing_lists/mailing-list-id \ 
  -H 'Authorization: YOUR_API_KEY' \ 
  -d 'name=Black Friday Leads' \ 
  -d 'recipients[0][address][name]=John Doe' \ 
  -d 'recipients[0][address][line]=123 Main St, Anytown, Anyplace' \ 
  -d 'recipients[0][address][postcode]=AB1 2CD' \ 
  -d 'recipients[0][variables][salutation]=Mr.'

Node.js SDK

Node.js

import Intelliprint from 'intelliprint'
const ip = Intelliprint('your-api-key-here')

const mailingList = await ip.mailing_lists.update('mailing-list-id', {
  name: 'Black Friday Leads',
  recipients: [
    {
      address: {
        name: 'John Doe',
        line: '123 Main St, Anytown, Anyplace',
        postcode: 'AB1 2CD'
      },
      variables: {
        salutation: 'Mr.'
      }
    }
  ]
})

Example response

200 · Successful response

JSON

{
  "id": "mal_eg",
  "object": "mailing_list",
  "account": "acc_eg",
  "name": "Black Friday Leads",
  "recipients": 1000,
  "variables": [
    {
      "name": "salutation"
    }
  ],
  "longest_address_line": "123 Main St, Anytown, Anyplace",
  "address_validation": {
    "requested": false,
    "completed": false,
    "recipients": {
      "passed": 0,
      "failed": 0
    }
  },
  "created": 1761955200
}

400 · Example error response

JSON

{
  "error": {
    "message": "Received unknown parameter: testmood (Did you mean testmode?)",
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "param": "testmood"
  }
}