API docs by Redocly

Direct Mail Manager v3 (1.0.0)

Direct Mail Manager Support Website: support@directmailmanager.com URL: https://directmailmanager.com

API Collection Schema Definition and Documentation for Direct Mail Manager (DMM) v3.0.

Run this collection in Postman

Mailing Lists

Mailing Lists group addresses together and allows sending a Postcard to all the addresses attached to them with one simple operation.

List all mailing lists

Returns a JSON object containing all Mailing Lists existing in DMM database. Unique ID, Mailing List name, creation and modification dates together with the object type as it lives in DMM database are all returned per Mailing List. By default the lists are returned sorted by creation date in descending order, but filters, sorting and pagination can also be applied to this endpoint by providing these as query parameters for the request.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string
Enum: "id" "name" "created_at" "addresses_count"

The name of the property to sort result by

filter[name]
string
Example: filter[name]=My mailing list

This filter is used for filtering the result set by the name (title) of the Mailing List. The compare logic applied is of type contains, so if the provided string is found anywhere in the description of the mailing lists, the the mailing list will be included in the result set. The actual value (the name of the mailing list) should be provided between the square brackets as a query parameter.

Responses

Response Schema: application/json
Array of objects (mailing_list)

list of mailing list

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{}

Create a mailing list

Creates a new mailing list object. When creating a mailing list, the name of the new mailing list is required to be provided in the body of the request as a JSON object. Metadata can also be provided in the same JSON object as part of the body of the current request. Any number of meta information can be provided when creating a mailing list. All the meta information will be saved and attached to the new mailing list and will be returned as part of the mailing list's details any time the list is queried.

NOTE: Addresses cannot be attached to the mailing list upon creation. Once the mailing list is created, this endpoint will return the unique ID of the new mailing list. This ID can be used later to attach addresses to the new mailing list using the addresses/{{adr_id}}/attach endpoint, where the unique ID of the address to be attached to the newly created mailing list must be provided as a query parameter and the mailing list's unique ID must be provided as a JSON object in the body of the request. Detaching addresses of the newly created mailing list is also possible by using the /addresses/{{adr_id}}/detach endpoint.

Authorizations:
Authorization
Request Body schema:
required
name
required
string <= 255 characters

The name of the mailing list, which should be a string no longer than 255 characters. Spaces, numbers and some special characters are also allowed to be used.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string (object)

Value is type of resource.

name
string <= 255 characters

The name of the mailing list, which should be a string no longer than 255 characters. Spaces, numbers and some special characters are also allowed to be used.

id
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$

Unique identifier prefixed with mlg_lst_.

addresses_count
integer

The number of addresses added to the current mailing list. This count includes all the addresses attached to the current mailing list, regardless of their archived or suppressed status (if any).

mailable_count
integer

This number is the most important value in DMM v3. It represents the number of addresses which are verified and valid for sending postcards. This value is determined by the mail strictness setting which can be modified in the client area of DMM v3 -> account settings page, which can be found here: https://app.directmailmanager.com/settings/account. The mail strictness setting has 3 values to choose from: strict, normal an relaxed.

Explanation:

  • strict: this setting allows Postcards to be sent only to those addresses where the address verification status is fully valid. No other addresses counts as mailable in case the mail strictness setting is set to strict.
  • normal: this setting allows Postcards to be sent also to corrected and accepted addresses.
  • relaxed: this setting allows Postcards to be sent to any address, regardless of their verification status. Even if the address verification returned an invalid status, this setting allows the usage of those addresses for sending postcards. For the invalid addresses there's a good chance that the postcard will be returned to sender, since the address might be incomplete or misspelled.

Request samples

Content type
{
  • "name": "My mailing list"
}

Response samples

Content type
application/json
{
  • "name": "My mailing list",
  • "created_at": "2020-03-18T12:57:21.000000Z",
  • "updated_at": "2020-03-18T12:57:21.000000Z",
  • "object": "string",
  • "id": "mlg_lst_616941213e7ec",
  • "address_count": 1,
  • "mailable_count": 1
}

Retrieve a mailing list

Returns a single Mailing List identified by it's unique ID, provided as a query parameter. The response contains all the information about the requested Mailing List, which are: the unique ID of the requested mailing list, list name, creation and last modification date, object type.

NOTE: This endpoint does not return the actual address objects from the requested Mailing List, only the above enumerated properties of the mailing list. For requesting the addresses added to a mailing list, please use the /api/mailing-lists/:mailing_list_uid/addresses endpoint.

Authorizations:
Authorization
path Parameters
mlg_lst_id
required
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$
Example: mlg_lst_5f07180419e2f

id of the mailing list

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string (object)

Value is type of resource.

name
string <= 255 characters

The name of the mailing list, which should be a string no longer than 255 characters. Spaces, numbers and some special characters are also allowed to be used.

id
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$

Unique identifier prefixed with mlg_lst_.

addresses_count
integer

The number of addresses added to the current mailing list. This count includes all the addresses attached to the current mailing list, regardless of their archived or suppressed status (if any).

mailable_count
integer

This number is the most important value in DMM v3. It represents the number of addresses which are verified and valid for sending postcards. This value is determined by the mail strictness setting which can be modified in the client area of DMM v3 -> account settings page, which can be found here: https://app.directmailmanager.com/settings/account. The mail strictness setting has 3 values to choose from: strict, normal an relaxed.

Explanation:

  • strict: this setting allows Postcards to be sent only to those addresses where the address verification status is fully valid. No other addresses counts as mailable in case the mail strictness setting is set to strict.
  • normal: this setting allows Postcards to be sent also to corrected and accepted addresses.
  • relaxed: this setting allows Postcards to be sent to any address, regardless of their verification status. Even if the address verification returned an invalid status, this setting allows the usage of those addresses for sending postcards. For the invalid addresses there's a good chance that the postcard will be returned to sender, since the address might be incomplete or misspelled.

Response samples

Content type
application/json
{
  • "name": "My mailing list",
  • "created_at": "2020-03-18T12:57:21.000000Z",
  • "updated_at": "2020-03-18T12:57:21.000000Z",
  • "object": "string",
  • "id": "mlg_lst_616941213e7ec",
  • "address_count": 1,
  • "mailable_count": 1
}

Update a mailing list

Updates an existing Mailing List object identified by the Mailing List's unique ID, provided as a query parameter. This update only allows changing the name of the Mailing List.

Authorizations:
Authorization
path Parameters
mlg_lst_id
required
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$
Example: mlg_lst_5f07180419e2f

id of the mailing list

Request Body schema:
required
name
required
string <= 255 characters

The name of the mailing list

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string (object)

Value is type of resource.

name
string <= 255 characters

The name of the mailing list, which should be a string no longer than 255 characters. Spaces, numbers and some special characters are also allowed to be used.

id
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$

Unique identifier prefixed with mlg_lst_.

addresses_count
integer

The number of addresses added to the current mailing list. This count includes all the addresses attached to the current mailing list, regardless of their archived or suppressed status (if any).

mailable_count
integer

This number is the most important value in DMM v3. It represents the number of addresses which are verified and valid for sending postcards. This value is determined by the mail strictness setting which can be modified in the client area of DMM v3 -> account settings page, which can be found here: https://app.directmailmanager.com/settings/account. The mail strictness setting has 3 values to choose from: strict, normal an relaxed.

Explanation:

  • strict: this setting allows Postcards to be sent only to those addresses where the address verification status is fully valid. No other addresses counts as mailable in case the mail strictness setting is set to strict.
  • normal: this setting allows Postcards to be sent also to corrected and accepted addresses.
  • relaxed: this setting allows Postcards to be sent to any address, regardless of their verification status. Even if the address verification returned an invalid status, this setting allows the usage of those addresses for sending postcards. For the invalid addresses there's a good chance that the postcard will be returned to sender, since the address might be incomplete or misspelled.

Request samples

Content type
{
  • "name": "Test Mailing List (updated name)"
}

Response samples

Content type
application/json
{
  • "name": "My mailing list",
  • "created_at": "2020-03-18T12:57:21.000000Z",
  • "updated_at": "2020-03-18T12:57:21.000000Z",
  • "object": "string",
  • "id": "mlg_lst_616941213e7ec",
  • "address_count": 1,
  • "mailable_count": 1
}

Delete a mailing list

Deletes a mailing list from DMM v3 database identified by it's unique ID, provided as a query parameter.

NOTE: No addresses attached to the mailing list will be deleted. The delete operation is not reversible, use with caution. All these addresses will remain attached to all other mailing lists they were attached to (if any), or these will exist in the database without a mailing list.

Authorizations:
Authorization
path Parameters
mlg_lst_id
required
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$
Example: mlg_lst_5f07180419e2f

id of the mailing list

Responses

Response Schema: application/json
id
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$

Unique identifier prefixed with mlg_lst_.

deleted
boolean (deleted)

Represents the result of the delete action and results in a boolean true/false response.

Response samples

Content type
application/json
{
  • "id": "mlg_lst_616941213e7ec",
  • "deleted": true
}

List mailing list addresses

Returns an address list together with detailed information of the requested Mailing List these belong to like first, last, previous and next page links (in case the list has too many addresses and pagination is applied), as well as meta information of the segment of addresses like the number of current page, the number of total pages, the number of addresses per page and a URL path where the current segment of addresses can be reached directly through the API.

The requested Mailing List contains address objects, which are also returned in the response of the request as a JSON object. All the address objects inside the returned list also contain address meta information like creation and last modification date, object type and linked meta information if this was provided when the address object has been created or imported.

Authorizations:
Authorization
path Parameters
mlg_lst_id
required
string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$
Example: mlg_lst_5f07180419e2f

id of the mailing list

query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string <text>
Enum: "id" "first_name" "last_name" "address_city" "address_state" "address_zip" "address_line1" "address_line2" "verification_status" "updated_at"

The name of the property to sort result by

filter[first_name]
string
Example: filter[first_name]=John

Custom filter which can be used for first name value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the first_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the first name partly matches the string provided in the filter.

filter[last_name]
string
Example: filter[last_name]=Doe

Custom filter which can be used for last name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the last_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the last name partly matches the string provided in the filter.

filter[address_city]
string
Example: filter[address_city]=New York

Custom filter which can be used for city name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_city property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the city name partly matches the string provided in the filter.

filter[address_state]
string
Example: filter[address_state]=FL

Custom filter which can be used for state abbreviation that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_state property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the state partly matches the string provided in the filter.

filter[address_zip]
string
Example: filter[address_zip]=34689

Custom filter which can be used for zip code value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the zip_code property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the zip code partly matches the string provided in the filter.

filter[address_line1]
string
Example: filter[address_line1]=425 East Spruce Street

Custom filter which can be used for address line 1 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line1 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 1 partly matches the string provided in the filter.

filter[address_line2]
string

Custom filter which can be used for address line 2 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line2 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 2 partly matches the string provided in the filter.

filter[verification_status]
string
Enum: "valid" "invalid"
Example: filter[verification_status]=valid

Custom filter which can be used for address verification status value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the verification_status property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the verification status partly matches the string provided in the filter.

Responses

Response Schema: application/json
Array of objects (address)

list of artworks

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Segments

Segments are saved filters which act like a mailing list. These are constructed based on logical conditions and relations (filters) which are applied to a list of addresses when requested and narrow down the result set of all the addresses that match the conditions defined as the segment.

List all segments

Returns a list of all the Segments existing in DMM v3 database. The Segments are returned sorted by creation date, most recent first. The data returned contains a list of all the segments as a JSON object together with all the segment's information like their unique ID, name, creation and update dates, address count that matches the filters and most importantly the set of the conditions (filters) which the segment is constructed of.

The conditions objects contains all the details of the rule set like column name from which the value is used in the condition, the logical operator used, the boolean logic applied and finally the date of creation and last modification. Sort, filter and search can also be applied to narrow down the result set returned by this endpoint's response. These can be provided as query parameters when using this endpoint.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string
Enum: "id" "name" "created_at" "total"

The name of the property to sort result by

filter[name]
string
Example: filter[name]=My Segment

This filter is used for filtering the result set by the name (title) of the segment. The compare logic applied is of type contains, so if the provided string is found anywhere in the name of the segments, the segment will be included in the result set. The actual value (the name of the segment) should be provided between the square brackets as a query parameter.

Responses

Response Schema: application/json
Array of objects (segment)

list of segments

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Create a segment

Creates a segment based on the conditions (filters) specified in the body of the request as a JSON object, together with the name of the segment. The segment creation process needs a custom rule set to be applied to the list of addresses. The result will be a narrow result set which will only contain address objects which matches the conditions based on the custom rule(s) provided in the body of the request.

The conditions are a list of logical and boolean operators (see the lists of these below) applied on different properties of the address objects, like zip code, first name, last name, etc. Any property of the address objects can be used when constructing the conditions of the segment, even multiple properties can be used in different conditions and these conditions can be related using the boolean operators (see detials below).

Available OPERATORS:

  • is
  • is_not
  • contains
  • not_contains
  • begins_with
  • ends_with
  • is_blank
  • is_not_blank

Available BOOLEAN values:

  • and
  • or
Authorizations:
Authorization
Request Body schema:
required
name
required
string <= 255 characters

The name of the Segment to be created

required
Array of objects (condition)

The conditions of the segment. This is the most important part of the segment, since these conditions construct the segment. These are filters that have a boolean logic relation between them (AND / OR) and the result set of addresses returned from the database narrowed down based on these conditions (filters) can be saved as a segment. The saved conditions which construct the segment can be modified or extended anytime using the /segments/{{list_segment_id}} endpoint, where the unique ID of the segment should be provided as a query parameter.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "segment"
Value: "segment"

Value is type of resource.

name
string <= 255 characters

The name of the Segment to be created

Array of objects (condition)

The conditions of the segment. This is the most important part of the segment, since these conditions construct the segment. These are filters that have a boolean logic relation between them (AND / OR) and the result set of addresses returned from the database narrowed down based on these conditions (filters) can be saved as a segment. The saved conditions which construct the segment can be modified or extended anytime using the /segments/{{list_segment_id}} endpoint, where the unique ID of the segment should be provided as a query parameter.

id
string (sgm_id) ^sgm_[a-z 0-9]+$

Unique identifier prefixed with sgm_.

total
integer

Request samples

Content type
{
  • "name": "My Segment",
  • "conditions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "sgm_6166bfde1b7d7",
  • "name": "My List Segment",
  • "total": 23,
  • "created_at": "2021-10-13T11:15:42.000000Z",
  • "updated_at": "2021-10-13T11:15:42.000000Z",
  • "conditions": [
    • {
      },
    • {
      }
    ],
  • "object": "segment"
}

Retrieve a segment

Retrieves the details of an existing segment rule, regardless of which Mailing List the addresses in the current segment belong to. The segment is identified by it's unique ID which was returned upon Segment creation and it should be provided as a query parameter for this endpoint.

The response is a JSON object which contains details about the Segment like it's unique ID, date of creation and last modification, the number of addresses that match the filter which is the base of the segment, and most importantly all the conditions (filter) specified which construct the current segment. The conditions objects contains all the details of the rules like, column from which the value is used in the condition, the logical operator used and the boolean logic applied.

Authorizations:
Authorization
path Parameters
sgm_id
required
string (sgm_id) ^sgm_[a-z 0-9]+$
Example: sgm_5f2ba56aa6d8e

id of the segment

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "segment"
Value: "segment"

Value is type of resource.

name
string <= 255 characters

The name of the Segment to be created

Array of objects (condition)

The conditions of the segment. This is the most important part of the segment, since these conditions construct the segment. These are filters that have a boolean logic relation between them (AND / OR) and the result set of addresses returned from the database narrowed down based on these conditions (filters) can be saved as a segment. The saved conditions which construct the segment can be modified or extended anytime using the /segments/{{list_segment_id}} endpoint, where the unique ID of the segment should be provided as a query parameter.

id
string (sgm_id) ^sgm_[a-z 0-9]+$

Unique identifier prefixed with sgm_.

total
integer

Response samples

Content type
application/json
{
  • "id": "sgm_6166bfde1b7d7",
  • "name": "My List Segment",
  • "total": 23,
  • "created_at": "2021-10-13T11:15:42.000000Z",
  • "updated_at": "2021-10-13T11:15:42.000000Z",
  • "conditions": [
    • {
      },
    • {
      }
    ],
  • "object": "segment"
}

Update a segment

This request updates a specific Segment, identified by it's unique ID. The update process requires a JSON object containing the name of the segment and most importantly the rule set (filters) which actually constructs the Segment.

Authorizations:
Authorization
path Parameters
sgm_id
required
string (sgm_id) ^sgm_[a-z 0-9]+$
Example: sgm_5f2ba56aa6d8e

id of the segment

Request Body schema:
required
name
required
string <= 255 characters

The name of the Segment to be created

required
Array of objects (condition)

The conditions of the segment. This is the most important part of the segment, since these conditions construct the segment. These are filters that have a boolean logic relation between them (AND / OR) and the result set of addresses returned from the database narrowed down based on these conditions (filters) can be saved as a segment. The saved conditions which construct the segment can be modified or extended anytime using the /segments/{{list_segment_id}} endpoint, where the unique ID of the segment should be provided as a query parameter.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "segment"
Value: "segment"

Value is type of resource.

name
string <= 255 characters

The name of the Segment to be created

Array of objects (condition)

The conditions of the segment. This is the most important part of the segment, since these conditions construct the segment. These are filters that have a boolean logic relation between them (AND / OR) and the result set of addresses returned from the database narrowed down based on these conditions (filters) can be saved as a segment. The saved conditions which construct the segment can be modified or extended anytime using the /segments/{{list_segment_id}} endpoint, where the unique ID of the segment should be provided as a query parameter.

id
string (sgm_id) ^sgm_[a-z 0-9]+$

Unique identifier prefixed with sgm_.

total
integer

Request samples

Content type
{
  • "name": "My Udated Segment Name",
  • "conditions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "sgm_6166bfde1b7d7",
  • "name": "My List Segment",
  • "total": 23,
  • "created_at": "2021-10-13T11:15:42.000000Z",
  • "updated_at": "2021-10-13T11:15:42.000000Z",
  • "conditions": [
    • {
      },
    • {
      }
    ],
  • "object": "segment"
}

Delete a segment

Deletes an existing Segment specified by it's unique ID, provided as a query parameter for this endpoint.

NOTE: None of the addresses nor the Mailing List the segment is created from (if any) will be deleted, only the rule set will be removed which actually constructs the Segment. Please note that the delete operation is not reversible, therefore the deleted Segment cannot be recovered after deletion.

Authorizations:
Authorization
path Parameters
sgm_id
required
string (sgm_id) ^sgm_[a-z 0-9]+$
Example: sgm_5f2ba56aa6d8e

id of the segment

Responses

Response Schema: application/json
id
string (sgm_id) ^sgm_[a-z 0-9]+$

Unique identifier prefixed with sgm_.

deleted
boolean (deleted)

Represents the result of the delete action and results in a boolean true/false response.

Response samples

Content type
application/json
{
  • "id": "sgm_616e88e60235d",
  • "deleted": true
}

List segmented addresses

Returns a list of addresses that match the filter conditions saved as the segment for which the result set is requested. The unique ID of the segment should be provided as a query parameter when using the current endpoint. The result set contains all the addresses that match the filter conditions saved as segment, each address object's details, custom fields, address verification status and detailed information and the mailing list(s) that the address(es) belong to. Meta information is also part of the result set, like creation and update dates, pagination tokens, address count, etc.

TIP: Filter, sort and search can also be used when querying the current endpoint. These can be provided as query parameters.

Authorizations:
Authorization
path Parameters
sgm_id
required
string (sgm_id) ^sgm_[a-z 0-9]+$
Example: sgm_5f2ba56aa6d8e

id of the segment

query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string <text>
Enum: "id" "first_name" "last_name" "address_city" "address_state" "address_zip" "address_line1" "address_line2" "verification_status" "updated_at"

The name of the property to sort result by

filter[first_name]
string
Example: filter[first_name]=John

Custom filter which can be used for first name value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the first_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the first name partly matches the string provided in the filter.

filter[last_name]
string
Example: filter[last_name]=Doe

Custom filter which can be used for last name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the last_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the last name partly matches the string provided in the filter.

filter[address_city]
string
Example: filter[address_city]=New York

Custom filter which can be used for city name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_city property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the city name partly matches the string provided in the filter.

filter[address_state]
string
Example: filter[address_state]=FL

Custom filter which can be used for state abbreviation that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_state property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the state partly matches the string provided in the filter.

filter[address_zip]
string
Example: filter[address_zip]=34689

Custom filter which can be used for zip code value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the zip_code property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the zip code partly matches the string provided in the filter.

filter[address_line1]
string
Example: filter[address_line1]=425 East Spruce Street

Custom filter which can be used for address line 1 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line1 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 1 partly matches the string provided in the filter.

filter[address_line2]
string

Custom filter which can be used for address line 2 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line2 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 2 partly matches the string provided in the filter.

filter[verification_status]
string
Enum: "valid" "invalid"
Example: filter[verification_status]=valid

Custom filter which can be used for address verification status value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the verification_status property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the verification status partly matches the string provided in the filter.

Responses

Response Schema: application/json
Array of objects (address)

list of artworks

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Custom Fields

Custom fields are used for storing virtually any information for contacts, beside the default and required address fields (for example birthday, voucher code, etc). These can also be used as dynamic variables for HTML artworks.

List all custom fields

Returns a list of all your existing custom fields from DMM v3's database together with all their details and meta information like created and updated timestamps, unique ID, type, the name of the custom field displayed in the client area, the actual merge tag for which the custom field is created for and it's default value. The list of the custom fields is returned as a JSON object sorted by creation date in a descending order, but custom filters and sorting can be applied to the result set by providing all the desired conditions as query parameters.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string
Enum: "id" "name" "type" "merge_tag" "default_value"

The name of the property to sort result by

filter[name]
string
Example: filter[name]=My Custom field

This filter is used for filtering the result set by the name (title) of the Custom Field. The compare logic applied is of type contains, so if the provided string is found anywhere in the name of the custom fields, the custom field will be included in the result set. The actual value (the name of the custom field) should be provided between the square brackets as a query parameter.

filter[type]
string
Enum: "text" "number" "date"
Example: filter[type]=text

This filter is used for filtering the result set by the type of the Custom Field. The compare logic applied is of type contains, so if the provided string is found anywhere in the type of the custom fields, the custom field will be included in the result set. The actual value (the type of the custom field) should be provided between the square brackets as a query parameter.

filter[merge_tag]
string
Example: filter[merge_tag]=my_custom_field

This filter is used for filtering the result set by the merge tag of the Custom Field. The compare logic applied is of type contains, so if the provided string is found anywhere in the merge tag of the custom fields, the custom field will be included in the result set. The actual value (the merge tag of the custom field) should be provided between the square brackets as a query parameter.

filter[default_value]
string
Example: filter[default_value]=Some default value

This filter is used for filtering the result set by the default value of the Custom Field (if it has been set). The compare logic applied is of type contains, so if the provided string is found anywhere in the default value of the custom fields, the custom field will be included in the result set. The actual value (the default value of the custom field) should be provided between the square brackets as a query parameter.

Responses

Response Schema: application/json
Array of objects (custom_field)

The list of all custom fields

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{}

Create a custom field

This endpoint serves for creating a new custom field. The custom field's merge_tag property will be used for matching the actual merge_tag detected inside the artwork HTML of the postcard and replacing it with the value provided from any address object.

IMPORTANT: The merge tags are only available for HTML artworks. Static artworks like PDF, JPG, JPEG, PNG do not support dynamic merge tag replacing.

Please see the explanation and examples below for a better understanding of the logic behind custom fields and bulk postcard creation process.

TIP: These custom fields can also be used (and are used) in the bulk postcard creation process, when a mailing list containing multiple address objects is used for generating postcards. The address objects should contain the custom fields keys with different values for each address object. The values will be used for each postcard generation when a merge_tag is found in the artwork HTML inside double curly braces.

EXAMPLES:

CUSTOM FIELD OBJECT EXAMPLE:

  {
      "name": "age",
      "type": "number",
      "merge_tag": "number_age",
      "default_value": ""
  }

Create a custom field first, define it's type and give it a name. A default value is also recommended for the custom field to be set. This default value will be used in case no value is provided from the address object when running the bulk process. The field_type can be merge_variable, number, text or date. This field is required to be defined when creating the custom field. In case the field_type is set to merge_variable, the field will be used when running a bulk postcard creation process.

This means that the process will try to find the custom field's merge_tag inside the provided artwork HTML between double curly braces. If the merge_tag is found, it will be replaced with the value set under the given address object, where the custom object's key should match the custom field's merge_tag. For better understanding and a more detailed explanation, please see the address object example below, as well as the /addresses POST endpoint's description and /postcard POST endpoint's description.

ADDRESS OBJECT EXAMPLE:

When creating an address object, the merge_tag of the custom field should be provided under the custom object as key, and a value which will actually be displayed on the postcard should be the value of the object.

  {
      "mailing_list_id": "mlg_lst_5f06ef28a5a93",
      "first_name": "John",
      "last_name": "Demo Doe",
      "company": "Test Company",
      "address_line1": "11310 Old Seward Hwy",
      "address_line2": "",
      "address_city": "Anchorage",
      "address_state": "AK",
      "address_zip": "99515",
      "address_zip4": "",
      "address_country": "US",
      "metadata": {
          "campaign":"test",
          "meta":"test"
      },
      "custom": {
          "genre": "Male",
          "age" : 22
      }
  }

Notice the object key genre under the custom object, which is part of the whole address object. This object key will be the custom field's merge_tag. If the custom field does not exist, this will not be used, regardless of being part of the address object.

NOTE: The custom field type should be merge_variable (when creating the custom field) for the merge tag to be recognised and replaced inside the applied artwork's HTML, when the bulk process is generating printable PDF postcards.

Authorizations:
Authorization
Request Body schema:
required
name
required
string <= 255 characters

The name of the custom field which will be used for diplaying the field on the list of custom fields in the client area of DMM.

type
required
string
Enum: "text" "number" "date"

The type of the custom field, which will define the area of usage. If this is set to merge_variable, the current custom field will be used in the bulk postcard creation process.

merge_tag
required
string

This is the name of the actual merge_tag used inside the artwork's HTML between double curly braces.

default_value
string or null

The default value will be used when no value is defined for the current custom field. This is not required since the custom field or merge_tag used in the bulk creation porcess can have an empty valueit's not required to be set.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "custom-field"
Value: "custom-field"

Value is type of resource.

name
string <= 255 characters

The name of the custom field which will be used for diplaying the field on the list of custom fields in the client area of DMM.

type
string
Enum: "text" "number" "date"

The type of the custom field, which will define the area of usage. If this is set to merge_variable, the current custom field will be used in the bulk postcard creation process.

merge_tag
string

This is the name of the actual merge_tag used inside the artwork's HTML between double curly braces.

default_value
string or null

The default value will be used when no value is defined for the current custom field. This is not required since the custom field or merge_tag used in the bulk creation porcess can have an empty valueit's not required to be set.

id
string (cfld_id) ^cfld_[a-z 0-9]+$

Unique identifier prefixed with cfld_.

Request samples

Content type
{
  • "name": "My Custom field",
  • "type": "text",
  • "merge_tag": "my_custom_field",
  • "default_value": "Some default value"
}

Response samples

Content type
application/json
{
  • "id": "cfld_61726b5c9712b",
  • "name": "My New Custom Field",
  • "type": "text",
  • "merge_tag": "my_new_custom_field",
  • "default_value": null,
  • "created_at": "2021-10-22T07:42:20.000000Z",
  • "updated_at": "2021-10-22T07:42:20.000000Z",
  • "object": "custom-field"
}

Retrieve a custom field

Retrieves an existing custom field object identified by it's unique ID, together with all it's details from DMM v3's database. For retrieving you need to specify the unique ID of the custom field, which was returned upon the custom field creation. The response object contains the unique ID of the custom field, name, type, merge tag, default value as well as the meta information like created and last updated timestamps.

Authorizations:
Authorization
path Parameters
cfld_id
required
string (cfld_id) ^cfld_[a-z 0-9]+$
Example: cfld_5f2ba56aa6d8e

id of the custom_field

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "custom-field"
Value: "custom-field"

Value is type of resource.

name
string <= 255 characters

The name of the custom field which will be used for diplaying the field on the list of custom fields in the client area of DMM.

type
string
Enum: "text" "number" "date"

The type of the custom field, which will define the area of usage. If this is set to merge_variable, the current custom field will be used in the bulk postcard creation process.

merge_tag
string

This is the name of the actual merge_tag used inside the artwork's HTML between double curly braces.

default_value
string or null

The default value will be used when no value is defined for the current custom field. This is not required since the custom field or merge_tag used in the bulk creation porcess can have an empty valueit's not required to be set.

id
string (cfld_id) ^cfld_[a-z 0-9]+$

Unique identifier prefixed with cfld_.

Response samples

Content type
application/json
{
  • "id": "cfld_61726b5c9712b",
  • "name": "My New Custom Field",
  • "type": "text",
  • "merge_tag": "my_new_custom_field",
  • "default_value": null,
  • "created_at": "2021-10-22T07:42:20.000000Z",
  • "updated_at": "2021-10-22T07:42:20.000000Z",
  • "object": "custom-field"
}

Update a custom field

Use this endpoint to update a custom field object identified by it's unique ID provided as a query parameter.

NOTE: The updatable properties of a custom field are name, type, merge_tag, default_value.

Authorizations:
Authorization
path Parameters
cfld_id
required
string (cfld_id) ^cfld_[a-z 0-9]+$
Example: cfld_5f2ba56aa6d8e

id of the custom_field

Request Body schema:
required
name
required
string <= 255 characters

The name of the custom field which will be used for diplaying the field on the list of custom fields in the client area of DMM.

type
required
string
Enum: "text" "number" "date"

The type of the custom field, which will define the area of usage. If this is set to merge_variable, the current custom field will be used in the bulk postcard creation process.

merge_tag
required
string

This is the name of the actual merge_tag used inside the artwork's HTML between double curly braces.

default_value
string or null

The default value will be used when no value is defined for the current custom field. This is not required since the custom field or merge_tag used in the bulk creation porcess can have an empty valueit's not required to be set.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "custom-field"
Value: "custom-field"

Value is type of resource.

name
string <= 255 characters

The name of the custom field which will be used for diplaying the field on the list of custom fields in the client area of DMM.

type
string
Enum: "text" "number" "date"

The type of the custom field, which will define the area of usage. If this is set to merge_variable, the current custom field will be used in the bulk postcard creation process.

merge_tag
string

This is the name of the actual merge_tag used inside the artwork's HTML between double curly braces.

default_value
string or null

The default value will be used when no value is defined for the current custom field. This is not required since the custom field or merge_tag used in the bulk creation porcess can have an empty valueit's not required to be set.

id
string (cfld_id) ^cfld_[a-z 0-9]+$

Unique identifier prefixed with cfld_.

Request samples

Content type
{
  • "name": "My Updated Custom field",
  • "type": "text",
  • "merge_tage": "my_updated_custom_field",
  • "default_value": "Some default value"
}

Response samples

Content type
application/json
{
  • "id": "cfld_61726b5c9712b",
  • "name": "My New Custom Field",
  • "type": "text",
  • "merge_tag": "my_new_custom_field",
  • "default_value": null,
  • "created_at": "2021-10-22T07:42:20.000000Z",
  • "updated_at": "2021-10-22T07:42:20.000000Z",
  • "object": "custom-field"
}

Delete a custom field

Delete a specific custom field identified by the custom field's unique ID, provided as a query parameter.

NOTE: Once deleted, the custom field cannot be recovered anymore, so use this endpoint with caution.

Authorizations:
Authorization
path Parameters
cfld_id
required
string (cfld_id) ^cfld_[a-z 0-9]+$
Example: cfld_5f2ba56aa6d8e

id of the custom_field

Responses

Response Schema: application/json
id
string (cfld_id) ^cfld_[a-z 0-9]+$

Unique identifier prefixed with cfld_.

deleted
boolean (deleted)

Represents the result of the delete action and results in a boolean true/false response.

Response samples

Content type
application/json
{
  • "id": "cfld_5f2ba56aa6d8e",
  • "deleted": true
}

Addresses

Addresses are the most important entities for Direct Mail Manager which define where the created postcards will be delivered, as well as the number of actual generated and printed postcard items.

List all addresses

Returns a JSON object which represents the list of all your address objects that exist in DMM v3 database. The addresses are returned sorted by creation date by default, but query param filters can be used provided as query parameters for sorting and filtering the requested list of addresses based on the given conditions.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string <text>
Enum: "id" "first_name" "last_name" "address_city" "address_state" "address_zip" "address_line1" "address_line2" "verification_status" "updated_at"

The name of the property to sort result by

filter[first_name]
string
Example: filter[first_name]=John

Custom filter which can be used for first name value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the first_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the first name partly matches the string provided in the filter.

filter[last_name]
string
Example: filter[last_name]=Doe

Custom filter which can be used for last name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the last_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the last name partly matches the string provided in the filter.

filter[address_city]
string
Example: filter[address_city]=New York

Custom filter which can be used for city name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_city property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the city name partly matches the string provided in the filter.

filter[address_state]
string
Example: filter[address_state]=FL

Custom filter which can be used for state abbreviation that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_state property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the state partly matches the string provided in the filter.

filter[address_zip]
string
Example: filter[address_zip]=34689

Custom filter which can be used for zip code value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the zip_code property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the zip code partly matches the string provided in the filter.

filter[address_line1]
string
Example: filter[address_line1]=425 East Spruce Street

Custom filter which can be used for address line 1 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line1 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 1 partly matches the string provided in the filter.

filter[address_line2]
string

Custom filter which can be used for address line 2 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line2 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 2 partly matches the string provided in the filter.

filter[verification_status]
string
Enum: "valid" "invalid"
Example: filter[verification_status]=valid

Custom filter which can be used for address verification status value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the verification_status property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the verification status partly matches the string provided in the filter.

show_archived
boolean
Example: show_archived=true

Custom filter which can be used for including the archived addresses in the result set. Using this query param will extend the result set to also contain address objects which have been archived.

with_suppressed
boolean
Example: with_suppressed=true

Custom filter which can be used for including the suppressed addresses in the result set. Using this query param will extend the result set to also contain suppressed address objects.

Responses

Response Schema: application/json
Array of objects (address)

list of artworks

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Create an address

Creates a new address object and saves it in DMM database. This endpoint also accepts metadata and custom fields to be provided beside the default and required address properties, which are listed below.

DEFAULT address object fields:
  • first_name
  • last_name
  • company
  • address_line1
  • address_line2
  • address_city
  • address_state
  • address_zip
  • address_zip4
  • address_country
REQUIRED address object fields:
  • first_name or company
  • address_line1
  • address_city
  • address_state
  • address_zip
METADATA address object fields:

This field type is used for filtering and matching to internal systems for example. Metadata is unique to each address object, and once provided it won't be applied to every address object.

If the same metadata applies to multiple address objects, it should be provided for each address object in particular. Metadata can be provided as a key:value pair of data.

Each metadata field should be added as a separate key:value pair inside the metadata object.

Limitations apply to metadata object, which are the following:

  • up to 20 key-value pairs of metadata can be provided
  • each key can be maximum 40 characters long
  • each value can be maximum 500 characters long
  • nested objects are not accepted

Example:

"metadata": {
    "campaign":"SUMMER2020",
    "internal_id":"322",
    "another_meta":"test"
  }
CUSTOM address object fields:

The custom fields represent data which is not needed by default as a porperty of an address object. If the user needs extra information saved to each address object, this can be achieved using the custom fields.

IMPORTANT A custom field must be first created using the /custom-fields endpoint before it can be used to store custom information at the address object. Only existing custom fields can be used when creating address object. These should be referenced by their key. If a custom field is not created before it is used when creating and address object, error won't be thrown here but the provided (inexistent) custom field simply won't be attached to the address object.

The major difference between metadata and custom fields is that once a custom field is provided, it will be visible and available for all address objects. If custom field is not provided for some address objects, the key will still appear for all address objects, but the value of these will be an empty string ''. Metadata will not be attached to address objects where it is not provided.

Custom fields can be provided as a key:value pair of data. Each custom field should be added as a separate key:value pair inside the custom object, where the key is the reference to the custom field which has to be created before it is used.

Example:

"custom": {
    "gender":"Male",
    "age":"23",
    "promo_code": "10DISCOUNT"
}
Authorizations:
Authorization
Request Body schema:
required
address_line1
required
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_city
required
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
required
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
required
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Request samples

Content type
{
  • "mailing_list_ids": [
    • "mlg_lst_5f29371e6f922"
    ],
  • "first_name": "John",
  • "last_name": "Doe",
  • "company": "My Company",
  • "address_line1": "11310 Old Seward Hwy",
  • "address_line2": null,
  • "address_city": "Anchorage",
  • "address_state": "AK",
  • "address_zip": "99515",
  • "address_country": "US",
  • "metadata": {
    • "campaign": "example_campaign",
    • "meta": "some meta"
    },
  • "custom": {
    • "genre": "Male",
    • "voucher_code": "10DISCOUNT"
    }
}

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

List all suppressed addresses

This endpoint serves for retrieving all the suppressed addresses from DMM v3 database, regardless of which list they were suppressed from. The response contains a detailed object including all properties of an address, like: first name, last name, company name, address line 1, address line 2, city, state, zip.

If there were custom fields attached to the address, these are also listed among the properties of the response object. Metadata is also useful, because it provides information about the suppressed address object, like the creation and update dates, etc It also contains details regarding the validity of the address aswell as the list name and the id, which the address was suppressed from.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string <text>
Enum: "id" "first_name" "last_name" "address_city" "address_state" "address_zip" "address_line1" "address_line2" "verification_status" "updated_at"

The name of the property to sort result by

filter[first_name]
string
Example: filter[first_name]=John

Custom filter which can be used for first name value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the first_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the first name partly matches the string provided in the filter.

filter[last_name]
string
Example: filter[last_name]=Doe

Custom filter which can be used for last name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the last_name property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the last name partly matches the string provided in the filter.

filter[address_city]
string
Example: filter[address_city]=New York

Custom filter which can be used for city name that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_city property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the city name partly matches the string provided in the filter.

filter[address_state]
string
Example: filter[address_state]=FL

Custom filter which can be used for state abbreviation that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_state property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the state partly matches the string provided in the filter.

filter[address_zip]
string
Example: filter[address_zip]=34689

Custom filter which can be used for zip code value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the zip_code property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the zip code partly matches the string provided in the filter.

filter[address_line1]
string
Example: filter[address_line1]=425 East Spruce Street

Custom filter which can be used for address line 1 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line1 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 1 partly matches the string provided in the filter.

filter[address_line2]
string

Custom filter which can be used for address line 2 that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the address_line2 property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the address line 2 partly matches the string provided in the filter.

filter[verification_status]
string
Enum: "valid" "invalid"
Example: filter[verification_status]=valid

Custom filter which can be used for address verification status value that exists inside the result set. Using this query param will narrow down the result to contain only objects matching the key specified in square brackets. In this case, it will be matched against the verification_status property of the address objects inside the database. The matching algorithm applied to the matching is partial match or "contains" meaning that all the addresses will be included in the result set where the verification status partly matches the string provided in the filter.

Responses

Response Schema: application/json
Array of objects (address)

list of artworks

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Retrieve an address

Retrieves an existing address object from DMM database together with all it's details. In order to retrieve it, you need to specify the unique ID of the address, which has been returned upon address creation.

Note: In case it's easier, you can find the address IDs in your account inside the client area of DMM v3. All you have to do is follow this link (log in if requested): https://app.directmailmanager.com/lists/address and search for the address you need. Once found, just hover over the initials displayed in a circle before the first name and click to copy the address ID to the clipboard, if needed.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

The unique ID of the address object (begins with adr_)

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Update an address

This endpoint is used for updating an address object. The update operation needs an address object in JSON format which is similar to the one used for creating an address. All the required parameters should be passed inside the JSON object sent as the body of the request.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

The unique ID of the address object (begins with adr_)

Request Body schema:
required
address_line1
required
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_city
required
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
required
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
required
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Request samples

Content type
{
  • "mailing_list_ids": [
    • "mlg_lst_5f29371e6f922"
    ],
  • "first_name": "John",
  • "last_name": "Doe",
  • "company": "My Company",
  • "address_line1": "11310 Old Seward Hwy",
  • "address_line2": null,
  • "address_city": "Anchorage",
  • "address_state": "AK",
  • "address_zip": "99515",
  • "address_country": "US",
  • "metadata": {
    • "campaign": "example_campaign",
    • "meta": "some meta"
    },
  • "custom": {
    • "genre": "Male",
    • "voucher_code": "10DISCOUNT"
    }
}

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Delete an address

Deletes an address object identified by it's unique ID. The address object cannot be deleted in case it is currently suppressed or locked because of being analyzed by an address verification service. This delete operation is not permanent, it's called "soft delete", and the addresses deleted using this endpoint can be restored anytime by sending a request to /addresses/:address_uid/restore.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

The unique ID of the address object (begins with adr_)

Responses

Response Schema: application/json
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

deleted
boolean (deleted)

Represents the result of the delete action and results in a boolean true/false response.

Response samples

Content type
application/json
{
  • "id": "adr_123456789",
  • "deleted": true
}

Restore an address

Once an address has been deleted, DMM v3 only deletes it using soft delete technique, meaning it does not remove it form the database. The deleted address only gets hidden from the user and all the other resources using it. This methodology is used mostly because of statistics which still needs the deleted entity. Because of applying this soft delete when deleting an address, DMM v3 is able to provide the ability to restore it simply by providing the deleted address object's unique ID to this endpoint as a query parameter.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

id of the address

Responses

Response samples

Content type
application/json
{
  • "error": {
    • "message": "The address_line1 field is required.",
    • "param": "address_line1",
    • "status_code": 422
    }
}

Suppress an address

Used for suppressing an address. In case an address is suppressed, it will be skipped for all Postcard send operations. No postcards will be sent to the suppressed addresses, regardless of how many mailing lists the suppressed address is added to. The current endpoint's success operation will set a suppressed flag for the address object specified in the request's body as a JSON object, meaning that the targeted address object will be suppressed. After the successful suppression of the address object, it will be available for viewing using the /addresses/suppressed endpoint, which returns all the suppressed address objects containing all their details.

TIP: When listing all the addressees from the database or when viewing the ones attached to a mailing list, you can also use the filter[with_suppressed] query parameter filter to include the suppressed addresses in the result set.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

id of the address

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Un-suppress an address

This endpoint is used for unsuppressing an address by providing it's unique ID as a query parameter. In case an address is suppressed it will be skipped for all postcard creation and send operations. This happens regardless of how many mailing lists is the suppressed address added to. In case the address still needs to be used for sending a postcard, it must be unsuppressed first.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

id of the address

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Attach address to a mailing list

This endpoint is used for adding an address to a mailing list. The unique ID of the address should be provided as a query parameter, while the mailing list's unique ID should be provided in the body of the request as a JSON object.

NOTE: The same address can be added to any number of mailing lists.

TIP: For removing the address from a mailing list, please use the /addresses/{address_id}/detach endpoint.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

id of the address

Request Body schema:
required
mailing_list_id
string

Unique identifier prefixed with mlg_lst_.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Request samples

Content type
{
  • "mailing_list_id": "mlg_lst_5f29371e6f922"
}

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Detach address from a mailing list

This endpoint is used for removing an address from a mailing list. The unique ID of the address should be provided as a query parameter, while the mailing list's unique ID should be provided in the body of the request as a JSON object.

TIP: For adding and address to a mailing list, please use the /addresses/{address_id}/attach endpoint.

Authorizations:
Authorization
path Parameters
adr_id
required
string (adr_id) ^adr_[a-zA-Z0-9]+$
Example: adr_5f293783e4ac2

id of the address

Request Body schema:
required
mailing_list_id
string

Unique identifier prefixed with mlg_lst_.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "address"
Value: "address"

Value is type of resource.

first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("to" address) first name. Either this first name or the company name is required to be used when creating an address.

last_name
string or null <= 40 characters

The address object's last name parameter. This will be the recipient's ("to" address) last name. This parameter is not required when creating an address object.

company
string or null <= 40 characters

The address object's company name parameter. This will be the recipient's ("to" address) company name. Either this company name or the first name is required to be used when creating an address.

address_line1
string <= 64 characters

The address object's address line 1 parameter. This will be the recipient's ("to" address) address line 1. This is a required parameter when creating an address object.

address_line2
string or null <= 64 characters

The address object's address line 2 parameter. This will be the recipient's ("to" address) address line 2. This parameter is not required when creating an address object.

address_city
string <= 200 characters

The address object's city parameter. This will be the recipient's ("to" address) city. This is a required parameter when creating an address object.

address_state
string <= 200 characters

The address object's state parameter. This will be the recipient's ("to" address) state. This is a required parameter when creating an address object.

address_zip
string <= 40 characters

The address object's zip code parameter. This will be the recipient's ("to" address) zip code. The zip code can be provided in the legacy 5 digit format or completed with zip4, by adding a dash and the extra 4 digits to the standard zip code like this: 12345-678. This is a required parameter when creating an address object.

address_country
string <= 2 characters
Default: "US"

The address object's country parameter. This will be the recipient's ("to" address) country. For now, this is US by default, since DMM is only available for US customers and addresses. This is a required parameter when creating an address object.

object (metadata) <= 20 properties

Metadata is used to store custom meta per object (object = any object that DMM uses, like: address object, mailing list object, postcard/letter object, artwork object, etc.) which can be used for back linking data to another system for example. In case it needs to be removed, an empty metadata array should be provided here. Otherwise, if no update needed in the metadata the current value should be provided. In case of update, just enter the new values in the array as key:value string. A few examples for sending meta: campaign, internal_id or another_meta:

"metadata": {
    "campaign":"SUMMER2022",
    "internal_id":"322",
    "another_meta":"test"
  }
id
string (adr_id) ^adr_[a-zA-Z0-9]+$

Unique identifier prefixed with adr_.

Array of objects (mailing_list)

The mailing list(s) which the address is linked to. This property is an array and it will contain multiple elements in case the address is present on multiple mailing lists at the same time. This property also contains detailed information and meta data about the mailing list like creation and last update timestamps, the mailing list's unique ID, name, count of total addresses attached to the mailing list and a mailable address count which is calculated based on the address's verification statuses.

validation_errors
string

Validation errors regarding the required properties of an address as well as the property type mismatches if data was not provided as required. This is an array of all the validation errors which happen on create/update operation of the address.

suppressed_at
string

Date and time when the address was suppressed.

deleted_at
string

Date and time when the address was deleted.

mailing_lists_count
string

Number of mailing lists where the address appears. The address object is linked to these many mailing lists.

verification_status
string

This is the address verification status of the created or updated address object. Every address is sent to an address verification service for validation upon creation or update. The address verification service responds with verification result and a list of all the corrections and/or adjustments applied to the address object (if any).

is_deliverable
string

The value of this property is calculated based on the address verification statuses. The strictness of this value can be modified by changing the mail strictness option inside the client area of DMM v3, or by following this link: https://app.directmailmanager.com/settings/account

Request samples

Content type
{
  • "mailing_list_ids": [
    • "mlg_lst_5f29371e6f922"
    ]
}

Response samples

Content type
application/json
{
  • "id": "adr_5f293783e4ac2",
  • "mailing_lists": [
    • {
      }
    ],
  • "validation_errors": null,
  • "suppressed_at": null,
  • "created_at": "2021-09-30T12:52:47.000000Z",
  • "updated_at": "2021-09-30T12:52:47.000000Z",
  • "deleted_at": null,
  • "mailing_lists_count": 1,
  • "verification_status": "valid",
  • "is_deliverable": true,
  • "object": "address"
}

Import addresses in bulk

Provides a way to add addresses in bulk to DMM v3 database through an import process which accepts CSV, XLS and XLSX datafiles. The datafile containing the list of addresses together with all their details including the required address fields should be uploaded to a file sharing service and made publicly accessible.

A link to the data file should be provided to this endpoint which, when requested will download the file to DMM v3 server and process it. When finished, the result of the import operation will be sent back to the requester entity through a webhook notification. In order to receive this, you have to first sign up for the webhook notification using the /webhook-subscriptions endpoint.

Authorizations:
Authorization
Request Body schema:
required
url
string

The publicly accessible URL of the data file which contains the list of addresses to be added to DMM v3 database in bulk.

mailing_list_id
string

The unique ID of the mailing list which the imported addresses should be added to. A batch of imported addresses can only be added to one mailing list upon import. All these addresses can be added to virtually any number of mailing lists after the import process has been completed.

with_header
boolean

This value tells DMM v3 how to parse the provided data file: if the data file contains a header which is the first row, the actual data will only be taken beginning with the second row. If this value is false, the data to be imported will be processed beginning with the first row of the data file.

object

Header mapping means telling DMM v3 which column in the provided data file contains the data required by DMM v3 for the address creation process. > Example: If the address line 1 property of the addresses provided as a data file are stored in the 4th column of the file which has a header named "Address", this has to be mapped to DMM v3's rules, which requires an "address_line1". This is done by simply providing the index of the 4th column (which is 3, counted from 0) as the key of the header_mapping -> fields object and the "address_line1" as the value.

Responses

Request samples

Content type
{
  • "url": "string",
  • "mailing_list_id": "string",
  • "with_header": true,
  • "header_mapping": {
    • "fields": {
      },
    • "custom_fields": {
      }
    }
}

Response samples

Content type
application/json
{
  • "error": {
    • "message": "The address_line1 field is required.",
    • "param": "address_line1",
    • "status_code": 422
    }
}

Artworks

Artwork defines the visual part of the postcard. It can be dynamic (HTML) or static (JPG, JPEG, PNG, PDF) and can contain images, texts styles and merge tags. Merge tags are dynamic variables replaced for each postcard from custom fields or default address properties.

List all artworks

Returns a list of all the artworks which exist in DMM database as (JSON) objects. The artworks are returned sorted by creation date by default, but filters can be used as query parameters for sorting and filtering the requested list of artworks based on given conditions.

Authorizations:
Authorization
query Parameters
page[number]
integer <int32>
Default: 1
Example: page[number]=2

A number that specifies which page's results to return in the response

page[size]
integer <int32> [ 1 .. 100 ]
Default: 10
Example: page[size]=10

A number which specifies how many objects to be returned per page (how long the result set should be)

date[from]
string <date-time> (created_at)
Example: date[from]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the beginning of the period for which the results should be returned from the database. Creation date of the entities is used here.

date[to]
string <date-time> (created_at)
Example: date[to]=2020-03-18T12:57:21.000000Z

Date filter to specify a date range to narrow the results down. This should be the end of the period for which the results should be returned from the database. Creation date of the entities is used here.

search
string <text>

The filter allows to search by any given string between the entities to be queried. The applied logic for the search term is "contains" and the search string is used in a case insensitive manner. The provided string will be matched against the entities which will be included in the search result in case the search term will be found anywhere inside the entities.

sort
string
Enum: "id" "name" "description" "created_at" "updated_at" "campaign_name" "user" "size" "type" "side"

The name of the property to sort result by.

filter[name]
string
Example: filter[name]=My Artwork

This filter is used for filtering the result set by the name (title) of the Artwork. The compare logic applied is of type contains, so if the provided string is found anywhere in the name of the artworks, the artwork will be included in the result set. The actual value (the name of the artwork) should be provided between the square brackets as a query parameter.

filter[description]
string
Example: filter[description]=My Artwork desctiption

This filter is used for filtering the result set by the description of the Artwork. The compare logic applied is of type contains, so if the provided string is found anywhere in the description of the artworks, the artwork will be included in the result set. The actual value (the description or part of the description of the artwork) should be provided between the square brackets as a query parameter.

filter[size]
string
Enum: "4x6" "6x9"
Example: filter[size]=4x6

This is used for filtering the result set by the size of the Artwork. The compare logic applied is of type contains, so if the provided string is found anywhere in the size of the artworks, the artwork will be included in the result set. The actual value (the size of the artwork) should be provided between the square brackets as a query parameter.

filter[side]
string
Enum: "front" "back"
Example: filter[side]=front

This is used for filtering the result set by the side of the Artwork. The compare logic applied is of type contains, so if the provided string is found anywhere in the side of the artworks, the artwork will be included in the result set. The actual value (the side of the artwork) should be provided between the square brackets as a query parameter.

Responses

Response Schema: application/json
Array of objects (artwork)

list of artworks

object (links)
object (meta)
object
string
Default: "list"
Value: "list"

Value is type of resource.

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "links": {},
  • "meta": {},
  • "object": "list"
}

Create an artwork

Creates a new artwork from a provided HTML document (HTML code) or static image files like JPG, JPEG, PNG or PDF.

NOTE: The body tag is mandatory when providing HTML code as artwork.

NOTE: Dynamic merge tags (merge variables) can only be used inside the HTML artwork and these should be provided between double curly brackets. Any merge tags provided between double curly brackets inside the static artwork types (JPG, JPEG, PNG or PDF) will not be replaced with values. These will appear on the final artwork design as they were provided (merge tags between double curly brackets). The response of the current endpoint will contain the rendered HTML with inline style which will be used at the Postcard generation phase and it will stand for the design of the final print ready PDF.

TIP: Metadata can also be attached to artwork objects in DMM v3 for storing any custom information which will be helpful later. For example when back linking to an external system needs to be applied.

Basic and general information is automatically saved and returned in the response of every created artwork version object, like created_at, updated_at timestamps and the type of the artwork object which is used for classification in DMM.

Versions: The Artwork generation and handling in DMM is structured with versions. Every modification/update applied to an artwork will generate a new version of the main artwork which was first created. The ID of the original artowrk will not change. All the artwork versions have their own unique IDs.

When the first artwork is created, the current endpoint's response will contain 2 versions: the basic (first) version of the artwork and the published version which will be used upon print ready PDF generation. Since this is the artwork creation process's first step, the first version and the published version returned inside the response of the endpoint will be identical.

Authorizations:
Authorization
Request Body schema:
required
name
required
string <= 255 characters

The name of the artwork.

size
required
string
Enum: "4x6" "6x9"
required
html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML code which constructs the artwork design. It can include inline CSS.

side
required
string
Enum: "front" "back"
description
string or null <= 255 characters

The description of the artwork (if any).

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "artwork"
Value: "artwork"

Value is type of resource.

name
string <= 255 characters

The name of the artwork.

description
string or null <= 255 characters

The description of the artwork (if any).

size
string
Enum: "4x6" "6x9"
side
string
Enum: "front" "back"
html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML code which constructs the artwork design. It can include inline CSS.

id
string (art_id) ^art_[a-z 0-9]+$

Unique identifier prefixed with art_.

Array of objects (artwork_version)

The unique ID of the artwork object.

object (artwork_version)

The description of the artwork version object.

Request samples

Content type
{
  • "name": "My Artwork",
  • "description": "My Artwork description",
  • "size": "4x6",
  • "side": "front",
  • "html": "<html><body>My HTML</body></html>"
}

Response samples

Content type
application/json
{
  • "id": "art_61700fb044bd3",
  • "name": "My Artwork",
  • "description": "Here goes the description of the artwork. This field is not required and can contain a long text if needed.",
  • "size": "4x6",
  • "side": "front",
  • "pdf_url": null,
  • "thumbnails": null,
  • "versions": [
    • {
      }
    ],
  • "published_version": {
    • "id": "art_vrsn_61700fb04d4d7",
    • "name": "My Artwork",
    • "description": "The published version of the artwork is the state which gets returned when the artwork is queried or used, identified by the artwork ID (version ID is not needed).\nThis published version can be changed anytime, by sending an artwork version ID in the body of the `/api/artworks/{{artwork_id}}` endpoint.",
    • "html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/REC-html40/loose.dtd\"><html><body>My HTML</body></html>",
    • "created_at": "2021-10-20T12:46:40.000000Z",
    • "updated_at": "2021-10-20T12:46:40.000000Z",
    • "object": "version"
    },
  • "metadata": [ ],
  • "campaign_name": null,
  • "user": null,
  • "created_at": "2021-10-20T12:46:40.000000Z",
  • "updated_at": "2021-10-20T12:46:40.000000Z",
  • "object": "artwork"
}

Retrieve an artwork

Retrieves all the details of an existing artwork object, identified by it's unique ID. For retrieving you need to specify the ID of the artwork, which was returned upon artwork creation.

NOTE: To view how the actual artwork looks like after it was uploaded and the PDF was generated (a PDF version will be generated regardless of the provided artwork's type) simply call the /artworks/{{artwork_id}}/generate-preview endpoint while providing the artwork's unique ID as a query parameter.

The ID of an artwork can also be discovered in the client area of DMM v3 by following this link: https://app.directmailmanager.com/artworks. Once there, search can be used to identify the exact artwork needed and the ID column of the table will contain the artwork ID.

Authorizations:
Authorization
path Parameters
art_id
required
string (art_id) ^art_[a-z 0-9]+$
Example: art_5f2ba56aa6d8e

id of the artwork

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "artwork"
Value: "artwork"

Value is type of resource.

name
string <= 255 characters

The name of the artwork.

description
string or null <= 255 characters

The description of the artwork (if any).

size
string
Enum: "4x6" "6x9"
side
string
Enum: "front" "back"
html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML code which constructs the artwork design. It can include inline CSS.

id
string (art_id) ^art_[a-z 0-9]+$

Unique identifier prefixed with art_.

Array of objects (artwork_version)

The unique ID of the artwork object.

object (artwork_version)

The description of the artwork version object.

Response samples

Content type
application/json
{
  • "id": "art_61700fb044bd3",
  • "name": "My Artwork",
  • "description": "Here goes the description of the artwork. This field is not required and can contain a long text if needed.",
  • "size": "4x6",
  • "side": "front",
  • "pdf_url": null,
  • "thumbnails": null,
  • "versions": [
    • {
      }
    ],
  • "published_version": {
    • "id": "art_vrsn_61700fb04d4d7",
    • "name": "My Artwork",
    • "description": "The published version of the artwork is the state which gets returned when the artwork is queried or used, identified by the artwork ID (version ID is not needed).\nThis published version can be changed anytime, by sending an artwork version ID in the body of the `/api/artworks/{{artwork_id}}` endpoint.",
    • "html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/REC-html40/loose.dtd\"><html><body>My HTML</body></html>",
    • "created_at": "2021-10-20T12:46:40.000000Z",
    • "updated_at": "2021-10-20T12:46:40.000000Z",
    • "object": "version"
    },
  • "metadata": [ ],
  • "campaign_name": null,
  • "user": null,
  • "created_at": "2021-10-20T12:46:40.000000Z",
  • "updated_at": "2021-10-20T12:46:40.000000Z",
  • "object": "artwork"
}

Update an artwork

Used for updating and Artwork object, identified by it's unique ID. Please note that only the name, description and published version of the artwork can be updated/modified/set using this endpoint.

VERSIONING:
This endpoint allows changing the currently published version of the Artwork by sending the version ID as part of the request's body in JSON format, under the published_version key.

Authorizations:
Authorization
path Parameters
art_id
required
string (art_id) ^art_[a-z 0-9]+$
Example: art_5f2ba56aa6d8e

id of the artwork

Request Body schema:
required
name
required
string <= 255 characters

The updated name of the artwork.

description
string or null <= 255 characters

The updated description of the artwork.

published_version
string^art_vrsn_[a-z 0-9]+$

The updated description of the artwork version.

Responses

Response Schema: application/json
created_at
required
string <date-time> (created_at)

A timestamp in ISO 8601 format of the date the resource was created.

updated_at
required
string <date-time> (updated_at)

A timestamp in ISO 8601 format of the date the resource was updated.

object
required
string
Default: "artwork"
Value: "artwork"

Value is type of resource.

name
string <= 255 characters

The name of the artwork.

description
string or null <= 255 characters

The description of the artwork (if any).

size
string
Enum: "4x6" "6x9"
side
string
Enum: "front" "back"
html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML code which constructs the artwork design. It can include inline CSS.

id