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
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",
  • "published_version": "art_vrsn_5f2ba56aa6d8e"
}

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"
}

Delete an artwork

Deletes an artwork object identified by it's unique ID. THIS PROCESS IS NOT REVERSIBLE. Please note that all versions of the specified artwork will be deleted as the result of using this endpoint.

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
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": "art_616e88e60235d",
  • "deleted": true
}

Get variables (merge tags) of a specific artwork

Used for identifying and listing all the merge tags from inside an artwork's HTML code, specified by it's unique ID as a query parameter. All the merge tags or merge variables that are added to the HTML between double curly brackets are automatically detected and listed in the current endpoint's response.

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
merge_variables
Array of strings

Response samples

Content type
application/json
{
  • "merge_variables": [
    • "first_name",
    • "last_name",
    • "voucher_code"
    ]
}

Generate preview of an artwork

This endpoint is used for generating an actual PDF preview of the already created artwork, identified by the artwork's unique ID. The result will be a URL where the actual generated PDF artwork can be previewed. The endpoint also returns the artwork thumbnail in 3 different sizes which is useful for displaying purposes.

TIP: Merge variables can also be provided as a JSON object in the body of the request which will be used when generating the preview to display any variable data used inside the artwork. This only works if the artwork type is HTML.

NOTE: The type property is required to be provided in the JSON object which represents the body of the request. For now, DMM v3 only supports Postcards and Letters, so the value should be either postcard or letter until Checks will be introduced.

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
type
required
string
Enum: "postcard" "letter"
merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

Responses

Response Schema: application/json
url
string <url>
object (thumbnail)

Request samples

Content type
{
  • "type": "postcard",
  • "merge_variables": {
    • "first_name": "John",
    • "discount": "80%",
    • "expires": "31 July, 2020"
    }
}

Artwork Versions

Artwork versions are designed to allow switching between different modifications/versions of an artwork. Every modification applied to the same artwork is saved as a different version. The version used by the artwork is called the published version and this can be set to any version of the artwork.

List all versions of an artowrk

Returns a list of all the versions of an artwork existing in DMM v3 database, identified by it's unique ID. The artwork ID should be provided as a URI query parameter. The list of the artwork versions is returned ordered by creation date, but filters can be used as query parameters for sorting and filtering the requested list based on given conditions.

In case there are too many versions saved to the requested artwork, the response will also contain a pagination logic with links to first, last, previous and next page(s) of the result set.

The given filter and sort conditions are also returned as part of the result set under a meta abject, which contains details like current page number, total number of results, number of results per page, current result set pointers (from, to) and an URI to the current path of results.

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

id of the artwork

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"

The name of the property to sort result by

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

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

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

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

Responses

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

list of artwork versions

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

Value is type of resource.

Response samples

Content type
application/json
{}

Create an artwork version

Creates a new version of an artwork specified by it's unique ID, which defines the exact artwork to create a new version for. The required data for the artwork version creation is the name of the new version and the actual HTML code which defines it. The provided HTML can contain inline CSS style. The required details must be provided as an URL encoded form data.

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

The name of the artwork version.

required
html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML content of the artwork version which stands as the base of the artwork design.

description
string or null

The 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: "version"
Value: "version"

Value is type of resource.

name
string

The name of the artwork version.

description
string or null

The description of the artwork version.

html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML content of the artwork version which stands as the base of the artwork design.

id
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$

Unique identifier prefixed with art_vrsn_.

Request samples

Content type
{
  • "name": "My Artwork Version",
  • "description": "My Artwork Version description",
  • "html": "<html>My HTML</html>"
}

Response samples

Content type
application/json
{
  • "id": "art_vrsn_61712e005e018",
  • "name": "My Artwork Version",
  • "description": "My Artwork Version description",
  • "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-21T09:08:16.000000Z",
  • "updated_at": "2021-10-21T09:08:16.000000Z",
  • "object": "version"
}

Retrieve a specific artwork version

Retrieves the details of an artwork version object identified by two key parameters: the unique ID of the artwork for which the version data should be retrieved and the unique ID of the artwork version.

These two unique IDs are always returned upon artwork version creation and both must be provided as a query parameter for this endpoint.

The JSON type response of this endpoint contains details about the requested artwork version such as it's unique ID, the name of the version, the actual html which defines the artwork (if the artwork's type is HTML, otherwise this field will be null) and also meta information such as created and updated timestamps and the object type defined in DMM v3's database.

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

id of the artwork

art_vrsn_id
required
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$
Example: art_vrsn_5f2ba56aa6d8e

id 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: "version"
Value: "version"

Value is type of resource.

name
string

The name of the artwork version.

description
string or null

The description of the artwork version.

html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML content of the artwork version which stands as the base of the artwork design.

id
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$

Unique identifier prefixed with art_vrsn_.

Response samples

Content type
application/json
{
  • "id": "art_vrsn_61712e005e018",
  • "name": "My Artwork Version",
  • "description": "My Artwork Version description",
  • "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-21T09:08:16.000000Z",
  • "updated_at": "2021-10-21T09:08:16.000000Z",
  • "object": "version"
}

Update a specific artwork version

Update an artwork version's name and description by using this endpoint. The artwork version to be updated can be specified by providing both unique ID's as a query parameter of the current endpoint: the artwork's unique ID which the version belongs to and the actual version's unique ID.

NOTE: only the name and the description of the artwork version can be updated. In case the HTML content of an artwork version needs update, this can only be achieved by updating the artwork itself, here: /artworks/{{artwork_id}} This operation creates a new artwork version and the new artwork version can be set as the published version by using this endpoint: To set a specific artwork version as the published version of the artwork, please use the /artworks/{id} PUT endpoint. /artworks/{{artwork_id}}

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

id of the artwork

art_vrsn_id
required
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$
Example: art_vrsn_5f2ba56aa6d8e

id of the artwork_version

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

The name of the artwork version to be set as the new name.

description
string or null <= 255 characters

The description of the artwork version to be set as the new description.

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: "version"
Value: "version"

Value is type of resource.

name
string

The name of the artwork version.

description
string or null

The description of the artwork version.

html_string (string) or remote_file_url (string) or local_file_path (string)

The HTML content of the artwork version which stands as the base of the artwork design.

id
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$

Unique identifier prefixed with art_vrsn_.

Request samples

Content type
{
  • "name": "My New Name for the Artwork Version",
  • "description": "My New Artwork Version description"
}

Response samples

Content type
application/json
{
  • "id": "art_vrsn_61712e005e018",
  • "name": "My Artwork Version",
  • "description": "My Artwork Version description",
  • "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-21T09:08:16.000000Z",
  • "updated_at": "2021-10-21T09:08:16.000000Z",
  • "object": "version"
}

Delete a specific artwork version

To delete an artwork version, send a DELETE type request to this endpoint, specifying the unique ID of the artwork and it's version's unique ID specified as query parameters parameters.

NOTE: This operation is not reversible, once the artwork version has been deleted, it can not be recovered anymore.

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

id of the artwork

art_vrsn_id
required
string (art_vrsn_id) ^art_vrsn_[a-z 0-9]+$
Example: art_vrsn_5f2ba56aa6d8e

id of the artwork_version

Responses

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

Unique identifier prefixed with art_vrsn_.

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": "art_vrsn_616e88e60235d",
  • "deleted": true
}

Postcards

The postcard is one of the main entities of Direct Mail Manager. The main components of a postcard are the artwork, a "to" address or a mailing list which defines the number of postcards to be generated and printed, mail type, send date and a name.

List all postcards

This endpoint retrieves all the postcards existing in DMM v3 database. One postcard's JSON response data contains all the information of the postcard like it's unique ID, the postcard's custom description, address objects defining the to_address and the from_address together with their unique IDs and meta information like creation and last update dates and also the address object type.

Beside these, artwork information is also included for each postcard in the result set.

The details about the attached artwork are: front and back artwork's unique ID, as well as their specific published version IDs used to generate the "visual part" (design) of the postcard. Important information per postcard can also be found in the response, like carrier used for delivering the printed version to the provided address(es), mail_type which defines the delivery speed, the size of the postcard in inches, number of targets the postcard will be sent to, total amount spent for printing and delivering the postcards, merge_variables if there were any defined (only applies in case the artwork type of the postcard is HTML) and the metadata information saved to the postcard.

NOTE: The number of targets the postcard will be sent to defines the exact number of printed pieces of the postcard batch which will have the same design and different "to" address.

Send date is also a very important property of the postcard, which defines the exact date when the printed versions should be mailed to the specified address.

NOTE: The closest send date available when creating a postcard is the next business day to the day the postcard is created.

Merge variables or merge_tags are also returned in the response which were used inside the HTML artwork (specified between double curly brackets in the HTML of the artwork).

Meta information is also part of the response, which is specific for each postcard inside the result set, like the created and last updated timestamps as well as the object type defined in DMM v3 database. The meta information can also contain custom information added by the user when creating the postcard, which usually helps easily identify the postcard or backlink it to different systems the postcard data was provided from.

Results are returned sorted in descending order by last creation date by default, but this can be overridden by providing the sort argument with the desired value as a query param. Custom filters, search term and sorting can be applied to the result set by providing these details as query parameters.

Pagination is applied to the result set by default, which can also be customized by providing pagination details as query parameters for the request. These can be used together with the filters, search term and sorting arguments.

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" "size" "mail_type" "created_by" "status" "items_count" "created_at" "updated_at" "targets" "campaign" "total_spent" "carrier" "created_by" "send_date" … 1 more

The name of the property to sort result by

filter[size]
string
Example: filter[size]=4x6

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

filter[status]
string
Example: filter[status]=pending

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

Responses

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

list of postcards

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

Value is type of resource.

Response samples

Content type
application/json
{}

Create a postcard

This endpoint allows creating a Postcard either by using the data already existing inside DMM (like artworks, mailing lists, addresses, custom fields), or by providing data for the Postcard on the fly, when requesting the current endpoint. Creating a postcard using DMM API is as easy as sending a simple request to this endpoint. Parameters are required to be provided for postcard creation as URL encoded form data.

The required parameters are listed below:

  • name : This parameter defines the name of the postcard
  • size : This parameter defines the actual size of the postcard
  • front_artwork : The front artwork of the the postcard, which can be provided in multiple formats
  • back_artwork : The back artwork of the the postcard, which can be provided in multiple formats
  • to_address : The address/addresses parameter defines where the postcard/postcards will be sent to, which can be provided in multiple formats
  • mail_type : This parameter defines the priority of mail delivery

NOTE: For more information please consult the above mentioned parameters in the "REQUEST BODY" section at the end of this endpoint's description

The current endpoint is the most sophisticated one out of the whole API collection: it accepts multiple types of information and allows creating postcard even if the required details are not saved in DMM's database.

It works in two different ways:

  • 1. It allows creating just one postcard per endpoint request in which case an address object needs to be sent within the request body, or it can create a postcard each time the endpoint is being called inside a loop while processing a list of addresses.
  • 2. It also provides a bulk postcard creation mechanism, where it can inteligently parse and create postcards from a provided mailing list of addresses. Meta information can also be added to each of the postcards, for later identification or backlinking to external applications. Meta information is also useful in campaigns and reports.

SINGLE POSTCARD CREATION

Single postcards can be created by simply providing the required information as a URL encoded form data. To and from addresses can be provided as references to already created address object in DMM's database. The reference should be the address object's unique ID returned upon address creation. These addresses can also be provided in the url encoded form data even if they are not already saved in DMM's database. Please see /addresses POST endpoint for the required details.

Size and send date are also vital and required information of the postcard creation process, which defines the desired printed size of the postcard and the date when it should be mailed.

Mail type is again an important property of the postcard creation process, which defines the priority of the mail delivery. Accepted options are "first class" or "standard" (standard is not available at the moment).
Merge variables can also be provided one-by-one if there are merge tags included in the artwork's HTML code between double curly braces.

Our API enables you to send HIPAA Compliant Postcards as well. In order to do so, you need include a single parameter in the request body: is_hipaa_compliant. This parameter has to be a boolean.

BULK POSTCARD CREATION

Multiple postcards can also be created "at once" by separately providing key informations for the postcard creation process. There are 2 properties which must be provided in a specific way to trigger the bulk postcard creation process: addresses and merge variables. To trigger bulk postcard creation process, instead of one address (reference or details) a mailing list should be provided, which is a list of multiple addresses saved and grouped inside DMM's database.

The mailing list can be provided using it's unqiue ID returned upon creation. In case of using the bulk postcard creation process, merge tags should also be provided in a different way: more exaclty by using custom fields, which can be first created at /custom-fields POST endpoint. By using these custom fields, merge variables can be provided to the artwork which contains merge tags inside the HTML code in duble curly braces. The merge tag should be exaclty the same as the custom field for the VDP logic to recognize and replace it accordingly.

The values of the custom fields should be set per address object, so for each address object a custom field must be specified as the key, and the value can vary per address object. When the bulk process runs, it will look for the existance of merge tags inside the artwork's HTML code, and if it finds some, it will instantly look for that key inside each address object's custom fields to get the value if it has been set and saved to the address object. More details for creating and saving these custom fields which will be used as merge tags or merge variables in the bulk postcard creation process can be found at /addresses POST endpoint and /custom-fields POST endpoint.

Authorizations:
Authorization
Request Body schema:
required

The request body should be provided as url encoded form data. The required fields vary based on the desired method of creation (single postcard or bulk generation processes) and whether the provided information exists or not in DMM's database. This information can be the artwork and it's desired version, the from and to addresses or a mailing list. These can be provided upon postcard creation directly as url encoded form data, or they can be specified as references (unique object ID's) if these items were previously created and saved in DMM's database.

NOTE: Any information supplied, with the exception of references serving as unique IDs to objects that are already present in DMM's database, will be automatically preserved, and a created unique ID will be returned in the postcard creation response. This enables the reuse of all the supplied data for a variety of tasks, such as additional or repetitive postcard generation procedures.

name
required
string <= 255 characters

The name of the created Postcard

required
adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object, identified by it's unique ID. The reference should be the unique ID of the address object obtained when the address object was created. It can also be retrieved from the client area of DMM v3, by following this link: https://app.directmailmanager.com/lists/address and search for the address you need. Once there, 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.

size
required
string
Enum: "4x6" "6x9"

The actual printed size of the created Postcard defined in inches

mail_type
required
string
Default: "first_class"
Enum: "first_class" "standard_class"

This attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track. standard_class mailing can not be used with 4x6 postcards or any postcards sent outside the United States.

required
art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Template examples:

required
art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Make sure to leave room for address and postage information by following the templates provided

Template examples:

description
string <= 255 characters

The description of the created Postcard

send_date
string <date>

The exact date when the postcard should be mailed to the specified to_address. The next day can be the closest send_date.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing company address object. The reference should be the unique ID of the company address object obtained when the address object was created. Company addresses can be retrieved by using this endpoint: /company-addresses.

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

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: "postcard"
Value: "postcard"

Value is type of resource.

name
string <= 255 characters

The name of the created Postcard

description
string <= 255 characters

The description of the created Postcard

size
string
Enum: "4x6" "6x9"

The actual printed size of the created Postcard defined in inches

mail_type
string
Default: "first_class"
Enum: "first_class" "standard_class"

This attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track. standard_class mailing can not be used with 4x6 postcards or any postcards sent outside the United States.

send_date
string <date>

The exact date when the postcard should be mailed to the specified to_address. The next day can be the closest send_date.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object, identified by it's unique ID. The reference should be the unique ID of the address object obtained when the address object was created. It can also be retrieved from the client area of DMM v3, by following this link: https://app.directmailmanager.com/lists/address and search for the address you need. Once there, 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.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing company address object. The reference should be the unique ID of the company address object obtained when the address object was created. Company addresses can be retrieved by using this endpoint: /company-addresses.

art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Template examples:

art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Make sure to leave room for address and postage information by following the templates provided

Template examples:

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

id
string (psc_id) ^psc_[a-z 0-9]+$

Unique identifier prefixed with psc_.

carrier
string
Default: "USPS"

The carrier name responsible for delivering the postcards to the provided addresses.

status
string
Enum: "pending" "scheduled" "preparing" "ongoing" "sent"

The actual status of the postcard.

string or string

In case the postcard has been cancelled by a user from the client area or through the API, this property will return the cancellation timestamp.

Request samples

Content type
{
  • "name": "My Postcard",
  • "description": "My Postcrad description",
  • "size": "4x6",
  • "mail_type": "first_class",
  • "send_date": "2020-03-18",
  • "to_address": {
    • "first_name": "John",
    • "last_name": "Doe",
    • "company": "My Company",
    • "address_line1": "11310 Old Seward Hwy",
    • "address_line2": "",
    • "address_city": "Anchorage",
    • "address_state": "AK",
    • "address_zip": "99515",
    • "address_country": "US"
    },
  • "from_address": {
    • "first_name": "John",
    • "last_name": "Doe",
    • "company": "My Company",
    • "address_line1": "11310 Old Seward Hwy",
    • "address_line2": "",
    • "address_city": "Anchorage",
    • "address_state": "AK",
    • "address_zip": "99515",
    • "address_country": "US"
    },
  • "front_artwork": "<html>HTML for {{user}}</html>",
  • "back_artwork": "art_5f2ba56aa6d8e",
  • "merge_variables": {
    • "name": "John Doe"
    },
  • "metadata": {
    • "internal_id": 1
    }
}

Response samples

Content type
application/json
{}

Retrieve a postcard

Use this endpoint to retrieve a postcard with all it's details from DMM v3 database. The required postcard should be identified by it's unique ID obtained upon postcard creation, and it must be provided as a query parameter for this endpoint.

The response contains all possible details of a postcard like unique ID, description (if provided), front and back artwork object's unique IDs together with their artwork_version_ID 's which were used for creating the postcard, the carrier which delivers the postcard, actual printable PDF file url, thumbnails urls for preview, merge_variables if these were provided, size of the postcard, status the postcard is currently in, mail_type which defines de delivery priority, specified delivery_date and the meta information like created and updated timestamps as well as the postcard's object type.

Send_date, cancellation_date, number of targets, total_spent amount for creating the requested postcard and the creator's name are also included in the result set. Meta information is returned.

Authorizations:
Authorization
path Parameters
psc_id
required
string (psc_id) ^psc_[a-z 0-9]+$
Example: psc_5f2ba56aa6d8e

id of the postcard

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: "postcard"
Value: "postcard"

Value is type of resource.

name
string <= 255 characters

The name of the created Postcard

description
string <= 255 characters

The description of the created Postcard

size
string
Enum: "4x6" "6x9"

The actual printed size of the created Postcard defined in inches

mail_type
string
Default: "first_class"
Enum: "first_class" "standard_class"

This attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track. standard_class mailing can not be used with 4x6 postcards or any postcards sent outside the United States.

send_date
string <date>

The exact date when the postcard should be mailed to the specified to_address. The next day can be the closest send_date.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object, identified by it's unique ID. The reference should be the unique ID of the address object obtained when the address object was created. It can also be retrieved from the client area of DMM v3, by following this link: https://app.directmailmanager.com/lists/address and search for the address you need. Once there, 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.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing company address object. The reference should be the unique ID of the company address object obtained when the address object was created. Company addresses can be retrieved by using this endpoint: /company-addresses.

art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Template examples:

art_id (string) or html_string (string) or remote_file_url (string) or local_file_path (string)

Can be an HTML string, a reference to an existing artwork object or a publicly accessible URL to the static artwork file (PDF).

Reference can be used in which case this should be the unique ID of the artwork object.

In case HTML is used, this must be a valid HTML and can contain CSS styling.

The published version of the artwork object will be used for the postcard generation.

Artwork Sizes:

  • 4.25"x6.25"
  • 6.25"x9.25"

Note: The supplied HTML will be rendered to the specified size.

Make sure to leave room for address and postage information by following the templates provided

Template examples:

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

id
string (psc_id) ^psc_[a-z 0-9]+$

Unique identifier prefixed with psc_.

carrier
string
Default: "USPS"

The carrier name responsible for delivering the postcards to the provided addresses.

status
string
Enum: "pending" "scheduled" "preparing" "ongoing" "sent"

The actual status of the postcard.

string or string

In case the postcard has been cancelled by a user from the client area or through the API, this property will return the cancellation timestamp.

Response samples

Content type
application/json
{}

Delete a postcard

This endpoint is used for permanently deleting a postcard from DMM v3 database. The postcard to be removed is identified by it's unique ID which must be provided as a query parameter.

NOTE: A postcard can only be deleted if it's status is "Draft" or "Sent". If the postcard needs to be deleted and it's status is not draft, it has to be cancelled first by using the following endpoint: /api/postcards/{{postcard_uid}}/cancel
NOTE: In case a postcard is deleted when it is in draft status, the process is not reversible and the postcard will be permanently deleted from the database. If the postcard status is sent when it gets deleted, the actual operation that happens is archive, so the operation is reversible, because instead of permanent delete, it only gets archived.

Authorizations:
Authorization
path Parameters
psc_id
required
string (psc_id) ^psc_[a-z 0-9]+$
Example: psc_5f2ba56aa6d8e

id of the postcard

Responses

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

Unique identifier prefixed with psc_.

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": "psc_616e88e60235d",
  • "deleted": true
}

Cancel a postcard

This endpoint is used for canceling a scheduled postcard before it gets processed by DMM mailing team. A postcard can be cancelled if it has a pending or scheduled status.

The timeframe before the postcard gets processed by the mailing team is called the cancellation window. This cancellation window size in hours is based on the account type (free or pro). A Free account has a 1 hour cancellation window while Pro account has a 1 hour cancellation window before the postcard gets processed by the mailing team.

NOTE: Presently the cancellation window is the same for Pro and Free accounts while DMM v3 is in beta phase

Authorizations:
Authorization
path Parameters
psc_id
required
string (psc_id) ^psc_[a-z 0-9]+$
Example: psc_5f2ba56aa6d8e

id of the postcard

Responses

Response samples

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

Letters

Letter is another mailable entity DMM v3 provides. It can contain up to 6 single sided or 12 pages if printed on both sides. It provides options for setting color properties (color or B&W), adding a blank first page to avoid to_address overlapping the content before the actual letter content and also the optin for printing on both sides of the paper or not.

List all letters

This endpoint retrieves all the letters existing in DMM v3 database. One letter's JSON response data contains all the information of the letter like it's unique ID, the letter's custom description, address objects defining the to_address and the from_address together with their unique IDs and meta information like creation and last update dates and also the address object type. Beside these, artwork information is also included for each letter in the result set. The details about the attached artwork are: the artwork's unique ID, as well as it's specific published version IDs used to generate the "visual part" (content and design) of the letter. Important information per letter can also be found in the response, like carrier used for delivering the printed version to the provided address(es), mail_type which defines the delivery speed, the size of the letter in inches, number of targets the letter will be sent to, total amount spent for printing and delivering the letters, merge_variables if there were any defined (only applies in case the artwork type of the letter is HTML) and the metadata information saved to the letter.

NOTE: The number of targets the letter will be sent to defines the exact number of printed pieces of the letter batch which will have the same design and different "to" address.

Send_date is also a very important property of the letter, which defines the exact date when the printed versions should be mailed to the specified address.

NOTE: The closest send date available when creating a letter is the next business day to the day the letter is created.

Merge variables or merge_tags are also returned in the response which were used inside the HTML artwork (specified between double curly brackets in the HTML of the artwork). This feature is under development. Coming soon.

Meta information is also part of the response, which is specific for each letter inside the result set, like the created and last updated timestamps as well as the object type defined in DMM v3 database. The meta information can also contain custom information added by the user when creating the letter, which usually helps easily identify the letter or backlink it to different systems the letter data was provided from.

Results are returned sorted in descending order by last creation date by default, but this can be overridden by providing the sort argument with the desired value as a query param. Custom filters, search term and sorting can be applied to the result set by providing these details as query parameters.

Pagination is applied to the result set by default, which can also be customized by providing pagination details as query parameters for the request. These can be used together with the filters, search term and sorting arguments.

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" "mail_type" "created_by" "status" "created_at" "updated_at" "targets" "campaign" "created_by" "send_date" "cancelled_at"

The name of the property to sort result by

filter[status]
string
Example: filter[status]=pending

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

Responses

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

list of letters

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

Value is type of resource.

Response samples

Content type
application/json
{}

Create a letter

This endpoint allows creating a letter either by using the data already existing inside DMM (like artwork, mailing lists, addresses, custom fields), or by providing data for the letter on the fly, when requesting the current endpoint. Creating a letter using DMM API is as easy as sending a simple request to this endpoint. Parameters are required to be provided for letter creation as URL encoded form data.

The required parameters are listed below:

  • name : This parameter defines the name of the letter
  • to_address : The address/addresses parameter defines where the letter/letters will be sent to
  • color : This is an important parameter because it defines whether the artwork will be colored or black & white
  • artwork : This parameter defines the artwork of a letter

NOTE: For more information please consult the above mentioned parameters in the "REQUEST BODY" section at the end of this endpoint's description

The current endpoint accepts multiple types of information and allows creating letter even if the required details are not saved in DMM's database.

It works in two different ways:

  • 1. It allows creating just one letter per endpoint request in which case an address object needs to be sent within the request body, or it can create a letter each time the endpoint is being called inside a loop while processing a list of addresses.
  • 2. It also provides a bulk letter creation mechanism, where it can inteligently parse and create letters from a provided mailing list of addresses.

Meta information can also be added to each of the letters, for later identification or backlinking to external applications. Meta information is also useful in campaigns and reports.

SINGLE LETTER CREATION

Single letters can be created by simply providing the required information as a URL encoded form data. To and from addresses can be provided as references to already created address object in DMM's database. The reference should be the address object's unique ID returned upon address creation. These addresses can also be provided in the url encoded form data even if they are not already saved in DMM's database. Please see /addresses POST endpoint for the required details.

Send date is also vital and required information of the letter creation process, which defines the date when the letter should be mailed.

Merge variables can also be provided one-by-one if there are merge tags included in the artwork's HTML code between double curly braces.

Our API enables you to send HIPAA Compliant Postcards as well. In order to do so, you need include a single parameter in the request body: is_hipaa_compliant. This parameter has to be a boolean.

BULK LETTER CREATION

Multiple letters can also be created "at once" by separately providing key informations for the letter creation process. There are 2 properties which must be provided in a specific way to trigger the bulk letter creation process: addresses and merge variables. To trigger bulk letter creation process, instead of one address (reference to an address object or address details) a mailing list should be provided, which is a list of multiple addresses saved and grouped inside DMM's database.

The mailing list can be provided using it's unqiue ID returned upon creation. In case of using the bulk letter creation process, merge tags should also be provided in a different way: more exaclty by using custom fields, which can be first created at /custom-fields POST endpoint.

By using these custom fields, merge variables can be provided to the artwork which contains merge tags inside the HTML code in duble curly braces. The merge tag should be exaclty the same as the custom field for the VDP logic to recognize and replace it accordingly. The values of the custom fields should be set per address object, so for each address object a custom field must be specified as the key, and the value can vary per address object.

When the bulk process runs, it will look for the existance of merge tags inside the artwork's HTML code, and if it finds some, it will instantly look for that key inside each address object's custom fields to get the value if it has been set and saved to the address object. More details for creating and saving these custom fields which will be used as merge tags or merge variables in the bulk letter creation process can be found at /addresses POST endpoint and /custom-fields POST endpoint.

Authorizations:
Authorization
Request Body schema:
required

The request body should be provided as url encoded form data. The required fields vary based on the desired method of creation (single letter or bulk generation processes) and whether the provided information exists or not in DMM's database. This information can be the artwork and it's desired version, the from and to addresses or a mailing list of addresses. These can be provided upon letter creation directly as url encoded form data, or they can be specified as references (unique object ID's) if these items were previously created and saved in DMM's database.

NOTE: Any information supplied, with the exception of references serving as unique IDs to objects that are already present in DMM's database, will be automatically preserved, and a created unique ID will be returned in the letter creation response. This enables the reuse of all the supplied data for a variety of tasks, such as additional or repetitive letter generation procedures.

name
required
string <= 255 characters

The name of the created Letter

required
adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

required
art_id (string) or remote_file_url (string) or local_file_path (string)

This is the actual content and design of the letter. It can be provided in three different ways:

  • using an artwork_id which is a reference to an already existing artwork in DMM v3 database
  • providing a publicly accessible URL to the artwork file, which will be downloaded by DMM v3
  • providing a binary file when users select a file from their computer and sends it to DMM v3.

Additional Notes: Every page of a supplied PDF file must be sized at 8.5"x11" Every page of the supplied HTML will be rendered and trimmed to 8.5"x11" size.

Page count limitations (Where a page represents a printable page from the provided artwork file. Please don't confuse it with sheets of paper):

  • 6 pages single sided
  • 12 pages double sided

PDFs that surpass the file limit will throw an error, while HTML that renders more pages than the file limit will be trimmed.

Letter Templates:

color
required
boolean

If provided, the letter will be printed in color. The values must be provided as boolean types. If true, the artwork of the letter will be printed in color else it will be black and white.

description
string <= 255 characters

The description of the created Letter

size
string
Value: "11x8.5"

The actual printed size of the created Letter defined in inches

send_date
string <date>

The exact date when the letter should be mailed to the specified to_address. The next day can be the closest send_date.

double_sided
boolean
Default: 1

If provided, the letter will be printed on both sides of the paper. The values must be provided as boolean types.

mail_type
string
Default: "first_class"
Enum: "first_class" "standard_class"

If provided this attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track.

address_placement
string
Default: "top_first_page"
Enum: "top_first_page" "insert_blank_page"

Defines how the to address will be placed on the printed letter.

By providing the:

  • top_first_page value, the address details will be placed in the upper left area of the first page of the letter, regardless if artwork or text content exists there. A white filled rectangle will be placed in front of the artwork containing the to_address details where the letter should be sent to.
  • insert_blank_page value, a new blank page will be inserted before the letter's first page and the address details will be printed on this new page, avoiding the overlapping of different content types on the letter artwork's first page.
cmpny_adr (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

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: "letter"
Value: "letter"

Value is type of resource.

name
string <= 255 characters

The name of the created Letter

description
string <= 255 characters

The description of the created Letter

size
string
Value: "11x8.5"

The actual printed size of the created Letter defined in inches

send_date
string <date>

The exact date when the letter should be mailed to the specified to_address. The next day can be the closest send_date.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

double_sided
boolean
Default: 1

If provided, the letter will be printed on both sides of the paper. The values must be provided as boolean types.

color
boolean

If provided, the letter will be printed in color. The values must be provided as boolean types. If true, the artwork of the letter will be printed in color else it will be black and white.

mail_type
string
Default: "first_class"
Enum: "first_class" "standard_class"

If provided this attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track.

address_placement
string
Default: "top_first_page"
Enum: "top_first_page" "insert_blank_page"

Defines how the to address will be placed on the printed letter.

By providing the:

  • top_first_page value, the address details will be placed in the upper left area of the first page of the letter, regardless if artwork or text content exists there. A white filled rectangle will be placed in front of the artwork containing the to_address details where the letter should be sent to.
  • insert_blank_page value, a new blank page will be inserted before the letter's first page and the address details will be printed on this new page, avoiding the overlapping of different content types on the letter artwork's first page.
cmpny_adr (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

art_id (string) or remote_file_url (string) or local_file_path (string)

This is the actual content and design of the letter. It can be provided in three different ways:

  • using an artwork_id which is a reference to an already existing artwork in DMM v3 database
  • providing a publicly accessible URL to the artwork file, which will be downloaded by DMM v3
  • providing a binary file when users select a file from their computer and sends it to DMM v3.

Additional Notes: Every page of a supplied PDF file must be sized at 8.5"x11" Every page of the supplied HTML will be rendered and trimmed to 8.5"x11" size.

Page count limitations (Where a page represents a printable page from the provided artwork file. Please don't confuse it with sheets of paper):

  • 6 pages single sided
  • 12 pages double sided

PDFs that surpass the file limit will throw an error, while HTML that renders more pages than the file limit will be trimmed.

Letter Templates:

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

id
string (ltr_id) ^ltr_[a-z 0-9]+$

Unique identifier prefixed with ltr_.

status
string
Enum: "pending" "scheduled" "preparing" "ongoing" "sent"

The actual status of the letter.

string or string

In case the letter has been cancelled by a user from the client area or through the API, this property will return the cancellation timestamp.

Request samples

Content type
{
  • "name": "My Letter",
  • "description": "My Letter description",
  • "send_date": "2020-03-18",
  • "mail_type": "first_class",
  • "color": true,
  • "double_sided": true,
  • "address_placement": "top_first_page",
  • "return_envelope": true,
  • "to_address": {
    • "first_name": "John",
    • "last_name": "Doe",
    • "company": "My Company",
    • "address_line1": "11310 Old Seward Hwy",
    • "address_line2": "",
    • "address_city": "Anchorage",
    • "address_state": "AK",
    • "address_zip": "99515",
    • "address_country": "US"
    },
  • "from_address": {
    • "first_name": "John",
    • "last_name": "Doe",
    • "company": "My Company",
    • "address_line1": "11310 Old Seward Hwy",
    • "address_line2": "",
    • "address_city": "Anchorage",
    • "address_state": "AK",
    • "address_zip": "99515",
    • "address_country": "US"
    },
  • "artwork": "https://html2pdf-golang.s3.amazonaws.com/PDFs/a85x11_letter_2_sided.pdf",
  • "merge_variables": {
    • "name": "John Doe"
    },
  • "metadata": {
    • "internal_id": 1
    }
}

Response samples

Content type
application/json
{}

Retrieve a letter

Use this endpoint to retrieve a letter with all it's details from DMM v3 database. The required letter should be identified by it's unique ID obtained upon letter creation, and it must be provided as a query parameter for this endpoint.

The response contains all possible details of a letter like unique ID, description (if provided), artwork object's unique ID together with it's artwork_version_ID 's which has been used for creating the letter, the carrier which delivers the letter, actual printable PDF file url, thumbnails urls for preview, size of the letter (currently only 8.5 x 11in supported), status the letter is currently in, mail_type which defines de delivery priority, specified delivery_date and the meta information like created and updated timestamps as well as the letter's object type.

Send_date, cancellation_date, number of targets, total_spent amount for creating the requested letter and the creator's name are also included in the result set. Meta information is returned.

Authorizations:
Authorization
path Parameters
ltr_id
required
string (ltr_id) ^ltr_[a-z 0-9]+$
Example: ltr_5f2ba56aa6d8e

id of the letter

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: "letter"
Value: "letter"

Value is type of resource.

name
string <= 255 characters

The name of the created Letter

description
string <= 255 characters

The description of the created Letter

size
string
Value: "11x8.5"

The actual printed size of the created Letter defined in inches

send_date
string <date>

The exact date when the letter should be mailed to the specified to_address. The next day can be the closest send_date.

adr_id (string) or mlg_lst_id (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

double_sided
boolean
Default: 1

If provided, the letter will be printed on both sides of the paper. The values must be provided as boolean types.

color
boolean

If provided, the letter will be printed in color. The values must be provided as boolean types. If true, the artwork of the letter will be printed in color else it will be black and white.

mail_type
string
Default: "first_class"
Enum: "first_class" "standard_class"

If provided this attribute defines the priority of mail delivery

Note: standard_class - a cheaper option that is less predictable, takes longer to deliver, and is harder to track.

address_placement
string
Default: "top_first_page"
Enum: "top_first_page" "insert_blank_page"

Defines how the to address will be placed on the printed letter.

By providing the:

  • top_first_page value, the address details will be placed in the upper left area of the first page of the letter, regardless if artwork or text content exists there. A white filled rectangle will be placed in front of the artwork containing the to_address details where the letter should be sent to.
  • insert_blank_page value, a new blank page will be inserted before the letter's first page and the address details will be printed on this new page, avoiding the overlapping of different content types on the letter artwork's first page.
cmpny_adr (string) or inline_address (object)

If provided, it can be a reference to an existing address object. The reference should be the unique ID of the address object obtained upon the address object was created.

art_id (string) or remote_file_url (string) or local_file_path (string)

This is the actual content and design of the letter. It can be provided in three different ways:

  • using an artwork_id which is a reference to an already existing artwork in DMM v3 database
  • providing a publicly accessible URL to the artwork file, which will be downloaded by DMM v3
  • providing a binary file when users select a file from their computer and sends it to DMM v3.

Additional Notes: Every page of a supplied PDF file must be sized at 8.5"x11" Every page of the supplied HTML will be rendered and trimmed to 8.5"x11" size.

Page count limitations (Where a page represents a printable page from the provided artwork file. Please don't confuse it with sheets of paper):

  • 6 pages single sided
  • 12 pages double sided

PDFs that surpass the file limit will throw an error, while HTML that renders more pages than the file limit will be trimmed.

Letter Templates:

merge_variables
object or null (merge_variables)

The variable data object, if there is any variable data inside the Mailable entity's (Postcard/Letter) artwork HTML code provided. If variable data is provided inside the address object, the merge_tag should be added to the Artwork between double curly braces.

NOTE: Variable data can only be used inside HTML artworks. The name of the variable can be a custom field or any default field of an address object, like address_line1, first_name, last_name, company, etc. Example: Let's say we would like to use the first name of the recipient and a voucher code dynamically for each Postcard/Letter, printed on the front, matched with the design (artwork). In this case, inside the HTML of the artwork the following 2 merge tags should be added and styled (using CSS) to match the design: {{first_name}} and {{voucher_code}}. Please note, that the voucher_code is not a default address field, so it must be created as a custom field first. You can read more about custom field creation when using this endpoint: /webhook-subscriptions.

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"
  }
is_hipaa_compliant
boolean

The is_hipaa_compliant parameter will make your Postcard HIPAA Compliant. Since this has to be a boolean, it can be either true or false.

id
string (ltr_id) ^ltr_[a-z 0-9]+$

Unique identifier prefixed with ltr_.

status
string
Enum: "pending" "scheduled" "preparing" "ongoing" "sent"

The actual status of the letter.

string or string

In case the letter has been cancelled by a user from the client area or through the API, this property will return the cancellation timestamp.

Response samples

Content type
application/json
{}

Delete a letter

This endpoint is used for permanently deleting a letter from DMM v3 database. The letter to be removed is identified by it's unique ID which must be provided as a query parameter.

NOTE: A letter can only be deleted if it's status is "Draft" or "Sent". If the letter needs to be deleted and it's status is not draft, it has to be cancelled first by using the following endpoint: /api/letters/{{letter_uid}}/cancel
NOTE: In case a letter is deleted when it is in draft status, the process is not reversible and the letter will be permanently deleted from the database. If the letter status is sent when it gets deleted, the actual operation that happens is archive, so the operation is reversible, because instead of permanent delete, it only gets archived.

Authorizations:
Authorization
path Parameters
ltr_id
required
string (ltr_id) ^ltr_[a-z 0-9]+$
Example: ltr_5f2ba56aa6d8e

id of the letter

Responses

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

Unique identifier prefixed with ltr_.

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": "ltr_616e88e60235d",
  • "deleted": true
}

Cancel a letter

This endpoint is used for canceling a scheduled letters before they are processed by DMM mailing team. A letter can be cancelled if it has a pending or scheduled status.

The timeframe before the letter gets processed by the mailing team is called the cancellation window. This cancellation window size in hours is based on the account type (free or pro). A Free account has a 1 hour cancellation window while Pro account has a 1 hour cancellation window before the letter gets processed by the mailing team.

NOTE: Presently the cancellation window is the same for Pro and Free accounts while DMM v3 is in beta phase

Authorizations:
Authorization
path Parameters
ltr_id
required
string (ltr_id) ^ltr_[a-z 0-9]+$
Example: ltr_5f2ba56aa6d8e

id of the letter

Responses

Response samples

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

Company addresses

List all company addresses

This endpoint returns all the addresses of the company the used API key belongs to. Company addresses are presaved address objects used for setting the return address of a mailable entity. 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.

Authorizations:
Authorization

Responses

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

The list of all company addresses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Create a company address

Creates a new company address object and saves it in DMM database. The default and required company address properties are listed below.

REQUIRED company address object fields:
  • address_line1
  • address_city
  • address_state
  • address_zip
Authorizations:
Authorization
Request Body schema:
required
first_name
string or null <= 40 characters

The address object's first name parameter. This will be the recipient's ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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.

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: "company-address"
Value: "company-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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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 ("from" 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.

id
string (cmpny_adr) ^cmpny_adr_[a-z 0-9]+$

Unique identifier prefixed with cmpny_adr_.

Request samples

Content type
{
  • "first_name": "Jeff",
  • "last_name": "Kingsford",
  • "company": "One Brand Marketing",
  • "address_line1": "425 East Spruce Street",
  • "address_line2": null,
  • "address_city": "Tarpon Springs",
  • "address_state": "FL",
  • "address_zip": "34689"
}

Response samples

Content type
application/json
{
  • "first_name": "Jeff",
  • "last_name": "Kingsford",
  • "company": "One Brand Marketing",
  • "address_line1": "425 East Spruce Street",
  • "address_line2": null,
  • "address_city": "Tarpon Springs",
  • "address_state": "FL",
  • "address_zip": "34689",
  • "created_at": "2020-03-18T12:57:21.000000Z",
  • "updated_at": "2020-03-18T12:57:21.000000Z",
  • "object": "company-address",
  • "id": "cmpny_adr_5f2ba56aa6d8e"
}