Mailing Lists group addresses together and allows sending a Postcard to all the addresses attached to them with one simple operation.
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.
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. |
Array of objects (mailing_list) list of mailing list | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": "null,",
- "address_count": 1,
- "metadata": [ ],
- "object": "mailing_list"
}, - {
- "id": "mlg_lst_616941213e7ec",
- "name": "My Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": "null,",
- "address_count": 1,
- "metadata": [ ],
- "object": "mailing_list"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2,
- "object": "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.
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. |
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 |
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.
|
{- "name": "My mailing list"
}
{- "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
}
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.
mlg_lst_id required | string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$ Example: mlg_lst_5f07180419e2f id of the mailing list |
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 |
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.
|
{- "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
}
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.
mlg_lst_id required | string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$ Example: mlg_lst_5f07180419e2f id of the mailing list |
name required | string <= 255 characters The name of the mailing list |
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 |
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.
|
{- "name": "Test Mailing List (updated name)"
}
{- "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
}
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.
mlg_lst_id required | string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$ Example: mlg_lst_5f07180419e2f id of the mailing list |
id | string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Represents the result of the delete action and results in a boolean true/false response. |
{- "id": "mlg_lst_616941213e7ec",
- "deleted": true
}
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.
mlg_lst_id required | string (mlg_lst_id) ^mlg_lst_[a-z 0-9]+$ Example: mlg_lst_5f07180419e2f id of the mailing list |
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. |
Array of objects (address) list of artworks | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "adr_5f2bc98f7cbb9",
- "mailing_lists": {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": 1,
- "mailable_count": 1,
- "metadata": [ ],
- "object": "mailing-list"
}, - "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,
- "address_country": "US",
- "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",
- "verification": {
- "status": "valid",
- "messages": {
- "success": [
- "Street name, city, state, and ZIP are all valid",
- "Entire address is valid"
]
}
}, - "is_deliverable": true,
- "object": "address"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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.
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.
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. |
Array of objects (segment) list of segments | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "sgm_616ffdde38eb7",
- "name": "My List Segment",
- "total": 2,
- "created_at": "2021-10-20T11:30:38.000000Z",
- "updated_at": "2021-10-20T11:30:38.000000Z",
- "conditions": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "or"
}, - {
- "column": "first_name",
- "value": "Cristal",
- "operator": "contains",
- "boolean": "and"
}
], - "object": "segment"
}, - {
- "id": "sgm_616e9e4f52d4a",
- "name": "My List Segment",
- "total": 10,
- "created_at": "2021-10-19T10:30:39.000000Z",
- "updated_at": "2021-10-19T10:30:39.000000Z",
- "conditions": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "or"
}
], - "object": "segment"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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
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. |
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 |
total | integer |
{- "name": "My Segment",
- "conditions": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "and"
}
]
}
{- "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": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "or"
}, - {
- "column": "first_name",
- "value": "Cristal",
- "operator": "contains",
- "boolean": "and"
}
], - "object": "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.
sgm_id required | string (sgm_id) ^sgm_[a-z 0-9]+$ Example: sgm_5f2ba56aa6d8e id of the segment |
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 |
total | integer |
{- "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": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "or"
}, - {
- "column": "first_name",
- "value": "Cristal",
- "operator": "contains",
- "boolean": "and"
}
], - "object": "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.
sgm_id required | string (sgm_id) ^sgm_[a-z 0-9]+$ Example: sgm_5f2ba56aa6d8e id of the segment |
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. |
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 |
total | integer |
{- "name": "My Udated Segment Name",
- "conditions": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "and"
}
]
}
{- "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": [
- {
- "column": "first_name",
- "value": "Maria",
- "operator": "contains",
- "boolean": "or"
}, - {
- "column": "first_name",
- "value": "Cristal",
- "operator": "contains",
- "boolean": "and"
}
], - "object": "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.
sgm_id required | string (sgm_id) ^sgm_[a-z 0-9]+$ Example: sgm_5f2ba56aa6d8e id of the segment |
id | string (sgm_id) ^sgm_[a-z 0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Represents the result of the delete action and results in a boolean true/false response. |
{- "id": "sgm_616e88e60235d",
- "deleted": true
}
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.
sgm_id required | string (sgm_id) ^sgm_[a-z 0-9]+$ Example: sgm_5f2ba56aa6d8e id of the segment |
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. |
Array of objects (address) list of artworks | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "adr_5f2bc98f7cbb9",
- "mailing_lists": {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": 1,
- "mailable_count": 1,
- "metadata": [ ],
- "object": "mailing-list"
}, - "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,
- "address_country": "US",
- "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",
- "verification": {
- "status": "valid",
- "messages": {
- "success": [
- "Street name, city, state, and ZIP are all valid",
- "Entire address is valid"
]
}
}, - "is_deliverable": true,
- "object": "address"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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.
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.
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. |
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. |
{- "data": [
- {
- "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"
}, - {
- "id": "cfld_61726b426e6db",
- "name": "My custom field",
- "type": "text",
- "merge_tag": "my_custom_field",
- "default_value": null,
- "created_at": "2021-10-22T07:41:54.000000Z",
- "updated_at": "2021-10-22T07:41:54.000000Z",
- "object": "custom-field"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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.
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.
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_tag required | string This is the name of the actual |
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. |
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_tag | string This is the name of the actual |
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 |
{- "name": "My Custom field",
- "type": "text",
- "merge_tag": "my_custom_field",
- "default_value": "Some default value"
}
{- "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"
}
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.
cfld_id required | string (cfld_id) ^cfld_[a-z 0-9]+$ Example: cfld_5f2ba56aa6d8e id of the custom_field |
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_tag | string This is the name of the actual |
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 |
{- "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"
}
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
.
cfld_id required | string (cfld_id) ^cfld_[a-z 0-9]+$ Example: cfld_5f2ba56aa6d8e id of the custom_field |
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_tag required | string This is the name of the actual |
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. |
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_tag | string This is the name of the actual |
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 |
{- "name": "My Updated Custom field",
- "type": "text",
- "merge_tage": "my_updated_custom_field",
- "default_value": "Some default value"
}
{- "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 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.
cfld_id required | string (cfld_id) ^cfld_[a-z 0-9]+$ Example: cfld_5f2ba56aa6d8e id of the custom_field |
id | string (cfld_id) ^cfld_[a-z 0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Represents the result of the delete action and results in a boolean true/false response. |
{- "id": "cfld_5f2ba56aa6d8e",
- "deleted": true
}
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.
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.
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. |
Array of objects (address) list of artworks | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "adr_5f2bc98f7cbb9",
- "mailing_lists": {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": 1,
- "mailable_count": 1,
- "metadata": [ ],
- "object": "mailing-list"
}, - "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,
- "address_country": "US",
- "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",
- "verification": {
- "status": "valid",
- "messages": {
- "success": [
- "Street name, city, state, and ZIP are all valid",
- "Entire address is valid"
]
}
}, - "is_deliverable": true,
- "object": "address"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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
orcompany
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 themetadata
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 separatekey:value
pair inside thecustom
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" }
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
|
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "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"
}
}
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
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. |
Array of objects (address) list of artworks | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "adr_5f2bc98f7cbb9",
- "mailing_lists": {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": 1,
- "mailable_count": 1,
- "metadata": [ ],
- "object": "mailing-list"
}, - "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,
- "address_country": "US",
- "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",
- "verification": {
- "status": "valid",
- "messages": {
- "success": [
- "Street name, city, state, and ZIP are all valid",
- "Entire address is valid"
]
}
}, - "is_deliverable": true,
- "object": "address"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 The unique ID of the address object (begins with adr_) |
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 The unique ID of the address object (begins with adr_) |
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
|
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "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"
}
}
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 The unique ID of the address object (begins with adr_) |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Represents the result of the delete action and results in a boolean true/false response. |
{- "id": "adr_123456789",
- "deleted": true
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 id of the address |
{- "error": {
- "message": "The address_line1 field is required.",
- "param": "address_line1",
- "status_code": 422
}
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 id of the address |
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 id of the address |
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 id of the address |
mailing_list_id | string Unique identifier prefixed with |
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "mailing_list_id": "mlg_lst_5f29371e6f922"
}
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Example: adr_5f293783e4ac2 id of the address |
mailing_list_id | string Unique identifier prefixed with |
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
| |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
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 |
{- "mailing_list_ids": [
- "mlg_lst_5f29371e6f922"
]
}
{- "id": "adr_5f293783e4ac2",
- "mailing_lists": [
- {
- "id": "mlg_lst_616941213e7ec",
- "name": "My New Mailing List",
- "created_at": "2021-10-15T08:51:45.000000Z",
- "updated_at": "2021-10-15T08:51:45.000000Z",
- "locked_at": null,
- "addresses_count": null,
- "mailable_count": null,
- "metadata": [
- {
- "key": "test1",
- "value": "value1"
}, - {
- "key": "test2",
- "value": "value2"
}
], - "object": "mailing-list"
}
], - "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"
}
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.
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 |
{- "url": "string",
- "mailing_list_id": "string",
- "with_header": true,
- "header_mapping": {
- "fields": {
- "0": "address_line1",
- "1": "company",
- "3": "first_name",
- "4": "address_line2",
- "5": "address_city",
- "7": "last_name",
- "9": "address_state",
- "11": "address_zip",
- "14": "address_country"
}, - "custom_fields": {
- "16": "birthday",
- "17": "voucher_code"
}
}
}
{- "error": {
- "message": "The address_line1 field is required.",
- "param": "address_line1",
- "status_code": 422
}
}
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.
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.
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. |
Array of objects (artwork) list of artworks | |
object (links) | |
object (meta) | |
object | string Default: "list" Value: "list" Value is type of resource. |
{- "data": [
- {
- "id": "art_61712e005470c",
- "name": "My Artwork",
- "description": "My detailed description of the artwork",
- "size": "4x6",
- "side": "front",
- "pdf_url": null,
- "thumbnails": null,
- "versions": [
- {
- "id": "art_vrsn_61712e005e018",
- "name": "My Artwork",
- "description": "My detailed description of the artwork version",
- "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"
}
], - "published_version": {
- "id": "art_vrsn_61712e005e018",
- "name": "My Artwork",
- "description": "My detailed description of the artwork version",
- "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"
}, - "metadata": [ ],
- "campaign_name": null,
- "user": " ",
- "created_at": "2021-10-21T09:08:16.000000Z",
- "updated_at": "2021-10-21T09:08:16.000000Z",
- "object": "artwork"
}, - {
- "id": "art_61712dfea60c8",
- "name": "My Artwork",
- "description": "My detailed description of the artwork",
- "size": "4x6",
- "side": "front",
- "pdf_url": null,
- "thumbnails": null,
- "versions": [
- {
- "id": "art_vrsn_61712dfeb14b3",
- "name": "My Artwork",
- "description": "My detailed description of the artwork version",
- "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:14.000000Z",
- "updated_at": "2021-10-21T09:08:14.000000Z",
- "object": "version"
}
], - "published_version": {
- "id": "art_vrsn_61712dfeb14b3",
- "name": "My Artwork",
- "description": "My detailed description of the artwork version",
- "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:14.000000Z",
- "updated_at": "2021-10-21T09:08:14.000000Z",
- "object": "version"
}, - "metadata": [ ],
- "campaign_name": null,
- "user": " ",
- "created_at": "2021-10-21T09:08:14.000000Z",
- "updated_at": "2021-10-21T09:08:14.000000Z",
- "object": "artwork"
}
], - "links": {
- "prev": null,
- "next": null
}, - "meta": {
- "current_page": 1,
- "from": 1,
- "last_page": 1,
- "links": [
- {
- "url": null,
- "label": "« Previous",
- "active": false
}, - {
- "label": "1",
- "active": true
}, - {
- "url": null,
- "label": "Next »",
- "active": false
}
], - "per_page": 10,
- "to": 2,
- "total": 2
}, - "object": "list"
}
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.
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). |
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 |
Array of objects (artwork_version) The unique ID of the artwork object. | |
object (artwork_version) The description of the artwork version object. |
{- "name": "My Artwork",
- "description": "My Artwork description",
- "size": "4x6",
- "side": "front",
- "html": "<html><body>My HTML</body></html>"
}
{- "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": [
- {
- "id": "art_vrsn_61700fb04d4d7",
- "name": "My Artwork",
- "description": "Versions are the different states of the artwork which suffered modifications.\nEverytime an artwork is modified, it will get a new version ID which can be used anytime needed.\nThe default version will always be the *published version* of the artwork.\nThis can be changed anytime.",
- "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"
}
], - "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"
}
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.
art_id required | string (art_id) ^art_[a-z 0-9]+$ Example: art_5f2ba56aa6d8e id of the artwork |
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 |
Array of objects (artwork_version) The unique ID of the artwork object. | |
object (artwork_version) The description of the artwork version object. |
{- "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": [
- {
- "id": "art_vrsn_61700fb04d4d7",
- "name": "My Artwork",
- "description": "Versions are the different states of the artwork which suffered modifications.\nEverytime an artwork is modified, it will get a new version ID which can be used anytime needed.\nThe default version will always be the *published version* of the artwork.\nThis can be changed anytime.",
- "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"
}
], - "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"
}
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 thepublished_version
key.
art_id required | string (art_id) ^art_[a-z 0-9]+$ Example: art_5f2ba56aa6d8e id of the artwork |
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. |
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 |