Documentation d'aide 〉API 〉

/projects/:document_identifier/address-groups/:address_group_uuid/addresses

Désolé, mais cet article d’aide n’est actuellement pas disponible en français. Si vous le souhaitez, vous pouvez consulter une traduction automatique effectuée par Google.

This resource supports the GET, PATCH, DELETE, and POST methods.

URL Parameters

Label Description
:document_identifier The project's document identifier
:address_group_uuid The UUID of the address group

GET

Returns an array of all the addresses in the group. If the group contains more than 1000 addresses, the results will be paginated. See "Pagination" in the Getting Started guide for more information.

GET Request Query String Parameters

Name Required Description
email No A comma-separated list of email addresses. Filters the result set to just addresses matching any of the given email address.
fields No A comma-separated list of the keys you want returned for each address. Default is to return all keys.

GET Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The resource could not be found or your API key has not been granted access to it
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
200 OK Success

GET Response Headers

Name Description
X-Total-Count The total number of addresses

GET Response Body

JSON representation of an array of objects. Each object in the array represents an address. Please consult the /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid resource for a description of the object keys for each address.

GET Example

GET /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Accept: application/json; charset=utf-8
Host: secure.directmailmac.com

HTTP/1.1 200 OK
Date: Wed, 22 Apr 2015 22:27:10 GMT
Content-Type: application/json; charset=utf-8
X-Total-Count: 2

[
    {
        "bounced": false,
        "company_name": null,
        "custom_1": "25",
        "custom_10": null,
        "custom_11": null,
        "custom_12": null,
        "custom_13": null,
        "custom_14": null,
        "custom_15": null,
        "custom_2": "F",
        "custom_3": "Redmond",
        "custom_4": "WA",
        "custom_5": "USA",
        "custom_6": null,
        "custom_7": null,
        "custom_8": null,
        "custom_9": null,
        "email": "janed@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "links": [
            {
                "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses/168CB548-14E5-4094-8367-8A8CE5BEA155",
                "rel": "self"
            },
            {
                "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2",
                "rel": "group"
            }
        ],
        "marked": true,
        "number_of_groups": 1,
        "subscribe_date": null,
        "unsubscribe_date": null,
        "unsubscribed": false,
        "uuid": "168CB548-14E5-4094-8367-8A8CE5BEA155"
    },
    {
        "bounced": false,
        "company_name": null,
        "custom_1": "23",
        "custom_10": null,
        "custom_11": null,
        "custom_12": null,
        "custom_13": null,
        "custom_14": null,
        "custom_15": null,
        "custom_2": "M",
        "custom_3": "Palo Alto",
        "custom_4": "CA",
        "custom_5": "USA",
        "custom_6": null,
        "custom_7": null,
        "custom_8": null,
        "custom_9": null,
        "email": "johnd@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "links": [
            {
                "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses/9484B79D-B294-450B-B588-9545E1B8523E",
                "rel": "self"
            },
            {
                "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2",
                "rel": "group"
            }
        ],
        "marked": true,
        "number_of_groups": 1,
        "subscribe_date": null,
        "unsubscribe_date": null,
        "unsubscribed": false,
        "uuid": "9484B79D-B294-450B-B588-9545E1B8523E"
    }
]

PATCH

Updates all the addresses in the group (if the email query string parameter is not given), or updates only the addresses in the group matching the query (if the email query string parameter is given).

PATCH Request Query String Parameters

Name Required Description
email No A comma-separated list of email addresses. Restricts the updated addresses to just those with a matching email address.

PATCH Request Body

A JSON object representing the properties you want to update. You may update the following keys:

Key Required Value Description
email No String The email address
first_name No String The first name
last_name No String The last name
company_name No String The company name
custom_1 No String Custom field #1
custom_2 No String Custom field #2
custom_3 No String Custom field #3
custom_4 No String Custom field #4
custom_5 No String Custom field #5
custom_6 No String Custom field #6
custom_7 No String Custom field #7
custom_8 No String Custom field #8
custom_9 No String Custom field #9
custom_10 No String Custom field #10
custom_11 No String Custom field #11
custom_12 No String Custom field #12
custom_13 No String Custom field #13
custom_14 No String Custom field #14
custom_15 No String Custom field #15
bounced No Boolean True if the address is marked as "Hard Bounced"
unsubscribed No Boolean True if the address is marked as "Unsubscribed
unsubscribe_date No String The unsubscribe date, in ISO-8601 format.
marked No Boolean True if the address is marked with a check mark in the Direct Mail user interface

PATCH Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The resource could not be found
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
202 Accepted The request has been accepted for processing

PATCH Response Body

A JSON object representing the merge task.

Key Value Description
links Array of Object URLs for the merge task and the updated resource.

PATCH Example

PATCH /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses?email=johnd%40example.com HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Content-Type: application/json; charset=utf-8
Host: secure.directmailmac.com
Content-Length: 31

{"company_name":"ABC Company."}

HTTP/1.1 202 Accepted
Date: Mon, 27 Apr 2015 22:48:13 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/merge-task?s=109&m=PATCH&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Faddress-groups%2FD0693CAB-1CAF-417A-8973-337DA5AD82F2%2Faddresses%3Femail%3Djohnd%2540example.com",
            "rel": "merge-task"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses?email=johnd%40example.com",
            "rel": "resource"
        }
    ]
}

DELETE

Removes all the addresses in the group (if the email query string parameter is not given), or removes only the addresses in the group matching the query (if the email query string parameter is given).

DELETE Request Query String Parameters

Name Required Description
email No A comma-separated list of email addresses. Restricts the updated addresses to just those with a matching email address.

DELETE Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The resource could not be found
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
202 Accepted The request has been accepted for processing

DELETE Response Body

A JSON object representing the merge task.

Key Value Description
links Array of Object URL for the merge task.

DELETE Example

DELETE /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/4F8956D5-03B4-473F-AD43-A818E148E89E/addresses?email=user113%40example.com%2Cuser110%40example.com HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Host: secure.directmailmac.com

HTTP/1.1 202 Accepted
Date: Mon, 27 Apr 2015 22:50:54 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/merge-task?s=110&m=DELETE&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Faddress-groups%2F4F8956D5-03B4-473F-AD43-A818E148E89E%2Faddresses",
            "rel": "merge-task"
        }
    ]
}

POST

Depending on the body of the request, the POSTS method either (1) adds a new address to the group or (2) adds to this group an address that already exists in another group. See the "Request Body" sections below for more information

POST Request Body (Inserting a New Address)

A JSON object representing the address.

Key Required Value Description
email Yes String The email address
first_name No String The first name
last_name No String The last name
company_name No String The company name
custom_1 No String Custom field #1
custom_2 No String Custom field #2
custom_3 No String Custom field #3
custom_4 No String Custom field #4
custom_5 No String Custom field #5
custom_6 No String Custom field #6
custom_7 No String Custom field #7
custom_8 No String Custom field #8
custom_9 No String Custom field #9
custom_10 No String Custom field #10
custom_11 No String Custom field #11
custom_12 No String Custom field #12
custom_13 No String Custom field #13
custom_14 No String Custom field #14
custom_15 No String Custom field #15
marked No Boolean True if the address should be marked with a check in the Direct Mail user interface. Defaults to true.
bounced No Boolean True if the address should be marked as "Hard Bounced". Defaults to false.
unsubscribed No Boolean True if the address should be marked as "Unsubscribed". Defaults to false.
unsubscribe_date No String The unsubscribe date, in ISO-8601 format.

POST Request Body (Linking to an Existing Address)

A JSON object representing the message.

Key Required Value Description
uuid Yes String The UUID of the address that you want to link to this group

POST Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The project could not be found
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
202 Accepted The request has been accepted for processing

POST Response Body

A JSON object representing the merge task.

Key Value Description
links Array of Object URLs for the merge task and the inserted resource.

POST Example

POST /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Content-Type: application/json; charset=utf-8
Host: secure.directmailmac.com
Content-Length: 117

{
    "company_name": "ABC Widgets, Inc.",
    "custom_1": "9",
    "email": "jackd@example.com",
    "first_name": "Jack",
    "last_name": "Doe"
}

HTTP/1.1 202 Accepted
Date: Wed, 22 Apr 2015 22:30:23 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/merge-task?s=51&m=POST&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Faddress-groups%2FD0693CAB-1CAF-417A-8973-337DA5AD82F2%2Faddresses%2FB4A4A0A7-84A4-474B-8A74-5A5CA50F3169",
            "rel": "merge-task"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups/D0693CAB-1CAF-417A-8973-337DA5AD82F2/addresses/B4A4A0A7-84A4-474B-8A74-5A5CA50F3169",
            "rel": "resource"
        }
    ]
}

Trouvez-vous cet article utile ? Oui | Non