Inserting, Updating, and Deleting Addresses

Spiacenti, questo articolo di supporto non è al momento tradotto in italiano. Se lo desideri, puoi provare una traduzione basata su Google.

Questo articolo di aiuto è per una versione precedente di Direct Mail.

This page contains documentation for version 1 of our API, which is now deprecated. New projects should use version 2.

The API supports the HTTP PUT and DELETE methods to insert, update, and delete addresses from a user's mailing list. Bulk and individual operations are supported, depending on the HTTP resource you access.

Endpoint

The API endpoint is https://secure.directmailmac.com

All requests must be sent using HTTP/1.1 and must include the Host: secure.directmailmac.com header.

Resources

Note that for all the resources listed below, you will need the Form ID from step #2 of the authorization process.

`/api/v1/forms/$form_id/addresses/$email_address`

DELETE

Removes an address from this mailing list. Example request:

DELETE /api/v1/forms/1234abab/addresses/user1%40example.com HTTP/1.1
Host: secure.directmailmac.com
Authorization: Basic QWxhZGluOnNlc2FtIG9wZW4=

Your request will return a 404 not found response if the email address is invalid (incorrect syntax). Remember that email addresses should be URI-encoded before using them as part of a URL.

PUT

Inserts or updates an address into this mailing list. The body of the request should be a JSON-encoded address dictionary (see definition below) that holds the data for the address. Example request:

PUT /api/v1/forms/1234abab/addresses/user1%40example.com HTTP/1.1
Host: secure.directmailmac.com
Authorization: Basic QWxhZGluOnNlc2FtIG9wZW4=

{
  "create_if_necessary": true,
  "address": {
    "first_name": "Mike",
    "last_name": "Jones",
    "company_name": "ABC Widgets, Inc.",
    "custom": { "1" : "650-555-1212" }
  }
}

Here's what happening in this example:

A new address with the email "user1@example.com" is created. The first name, last name, company name, and custom 1 fields are set.

Your request will return a 404 response if the email address is invalid (incorrect syntax), and will fail if the body includes invalid values in the address dictionaries.

`/api/v1/forms/$form_id/addresses`

DELETE

Remove addresses from this mailing list. The body of the request should be a JSON-encoded array of email addresses. Example request:

DELETE /api/v1/forms/1234abab/addresses HTTP/1.1
Host: secure.directmailmac.com
Authorization: Basic QWxhZGluOnNlc2FtIG9wZW4=

[
  "user1@example.com",
  "user2@example.com",
  "user3@example.com"
]

Your request will fail if it includes invalid (incorrect syntax) email addresses or over 100 email addresses at a time.

PUT

Inserts or updates addresses into this mailing list. The body of the request should be a JSON-encoded dictionary describing the updates to be performed. The dictionary keys are the email addresses to insert or update, and the dictionary values are address dictionaries (see definition below) that holds the data for each address. Example request:

PUT /api/v1/forms/1234abab/addresses HTTP/1.1
Host: secure.directmailmac.com
Authorization: Basic QWxhZGluOnNlc2FtIG9wZW4=

{
  "user1@example.com": {
    "create_if_necessary": true,
    "address": {
      "first_name": "Mike",
      "last_name": "Jones",
      "company_name": "ABC Widgets, Inc.",
      "custom": { "1" : "650-555-1212" }
    }
  },
  "user2@example.com": {
    "create_if_necessary": true,
    "address": {
      "first_name": "Rod",
      "last_name": "Green"
    }
  },
  "user3@example.com": {
    "create_if_necessary": false,
    "address": {
      "email": "user3-new@example.com",
      "custom": { "1" : null }
    }
  }
}

Here's what happening in this example:

A new address with the email "user1@example.com" is created. The first name, last name, company name, and custom 1 fields are set.
A new address with the email "user2@example.com" is created. The first name and last name fields are set.
The address with email "user3@example.com" is edited (if an address with this email does not exist in the mailing list, this edit is ignored). The email address is changed to user3-new@example.com and the custom 1 field is cleared.

Your request will fail if the body includes invalid (incorrect syntax) email addresses or invalid values in the address dictionaries.

Address Dictionaries

Address dictionaries describe the changes made to an address. Example:

{
  "create_if_necessary": true,
  "address": {
    "flags": {
      "=": [
        "bounced",
        "unsubscribed"
      ]
    },
    "marked": true,
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "ABC Widgets",
    "email": "user1@example.com",
    "unsubscribe_date": "2012-11-05T08:15:30-05:00",
    "custom": {
      "1": "a custom value for the Custom 1 field",
      "2": "a custom value for the Custom 2 field",
      "3": "a custom value for the Custom 3 field",
      "4": "a custom value for the Custom 4 field",
      "5": "a custom value for the Custom 5 field",
      "6": "a custom value for the Custom 6 field",
      "7": "a custom value for the Custom 7 field",
      "8": "a custom value for the Custom 8 field",
      "9": "a custom value for the Custom 9 field",
      "10": "a custom value for the Custom 10 field",
      "11": "a custom value for the Custom 11 field",
      "12": "a custom value for the Custom 12 field",
      "13": "a custom value for the Custom 13 field",
      "14": "a custom value for the Custom 14 field",
      "15": "a custom value for the Custom 15 field"
    }
  }
}

Description of Keys

create_if_necessary: Optional. If true, a new address is created and added to the mailing list if an address with the same email address cannot be found in the list. If an address with the same email address already exists in the list, then the properties you specify in the address dictionary (e.g. first_name, last_name, etc.) will be applied to the existing address. If false, a new address will not be created, but if an address with the same email address already exists in the list, then the properties you specify in the address dictionary will be applied to the existing address. Defaults to true.
address: Required. A dictionary with the address values to change.
address.flags: Optional. The value for this key is a dictionary describing how you want to change the flags. The dictionary can have either =, +, or - keys, depending on if you want to set, add, or remove flags. The value for the =, +, and - keys should be an array of strings, where each string corresponds to the flag you want set. Only the unsubscribed and bounced flags are supported. In the above example, both the bounced and unsubscribed flags are being set on this address.
address.marked: Optional. If true, the address is marked with a checked checkbox in Direct Mail. If false, the checkbox is cleared.
address.first_name: Optional. A string with the first name. Use null to clear the first name.
address.last_name: Optional. A string with the last name. Use null to clear the last name.
address.company_name: Optional. A string with the company name. Use null to clear the company name.
address.email: Optional. A string with the email address. Email address must not be null.
address.unsubscribe_date: Optional. A string with the ISO-8601 formatted unsubscribe date. Use null to clear the unsubscribe date.
address.custom: Optional. A dictionary where each key corresponds to the custom field you want to set, and each value is the custom field value. Using null for a key's value will clear the corresponding custom field.

Endpoint

Resources

/api/v1/forms/$form_id/addresses/$email_address

/api/v1/forms/$form_id/addresses

Address Dictionaries

Description of Keys

Perché aspettare? Direct Mail è gratis da provare!

`/api/v1/forms/$form_id/addresses/$email_address`

`/api/v1/forms/$form_id/addresses`