Browse API reference

Create a mailing list recipient

posthttps://api.intelliprint.net/v1/mailing_lists/{mailing_list}/recipients

Creates a single new mailing list recipient.

Parameters

Path

mailing_listrequired

string

The ID of the mailing list the recipient belongs to.

Request body

application/json

addressrequired

object

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"

variables

object

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

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 recipient.

Example"mal_rcp_eg"

object

string

The type of the object. Always mailing_list_recipient.

Allowed valuesmailing_list_recipient

mailing_list

string

The ID of the mailing list that the recipient belongs to.

Example"mal_eg"

account

string

The Intelliprint account ID that the mailing list belongs to.

Example"acc_eg"

address

object

namestring

The name of the recipient.

Example"John Doe"

linestring

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"

variables

object

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

address_validation_status

string

The address validation status for this recipient's address. Address validation for a recipient is only performed if address validation has been requested for the mailing list.

Allowed valuespassedfailedpendingnot_requested

Default"not_requested"

created

integer<int64>

The UNIX timestamp of when the mailing list recipient 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 'address[name]=John Doe' \ 
  -d 'address[line]=123 Main St, Anytown, Anyplace' \ 
  -d 'address[postcode]=AB1 2CD' \ 
  -d 'variables[salutation]=Mr.'

Node.js SDK

Node.js

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

const recipient = await ip.mailing_list_recipients.create('mailing-list-id', {
  address: {
    name: 'John Doe',
    line: '123 Main St, Anytown, Anyplace',
    postcode: 'AB1 2CD'
  },
  variables: {
    salutation: 'Mr.'
  }
})

Example response

200 · Successful response

JSON

{
  "id": "mal_rcp_eg",
  "object": "mailing_list_recipient",
  "mailing_list": "mal_eg",
  "account": "acc_eg",
  "address": {
    "name": "John Doe",
    "line": "123 Main St, Anytown, Anyplace",
    "postcode": "AB1 2CD",
    "country": "GB"
  },
  "variables": {
    "salutation": "Mr.",
    "internal_id": "12345",
    "loginURL": "https://abc.xyz/login"
  },
  "address_validation_status": "not_requested",
  "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"
  }
}