openapi: 3.1.0 info: title: Email contacts version: 2.0.1 description: 'Deprecated v2 endpoints for managing email contacts. Use this API to create, retrieve, update, and delete individual contacts; bulk-import contacts from a JSON collection or a base64-encoded file; record consent information and marketing preferences; and query contacts by address-book membership, creation date, or modification date. All endpoints in this spec are deprecated — new integrations should use the v3 Contacts API instead.' x-readme: headers: [] explorer-enabled: true proxy-enabled: true x-readme-fauxas: true x-samples-languages: - curl - csharp - java - javascript - node - python - php - ruby externalDocs: description: Learn more about Dotdigital APIs url: https://developer.dotdigital.com servers: - url: https://{region}-api.dotdigital.com variables: region: default: r1 enum: - r1 - r2 - r3 description: The Dotdigital region id your account belongs to security: - basicAuth: [] components: securitySchemes: basicAuth: type: http scheme: basic paths: /v2/contacts/deletion/{deletionRequestId}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get bulk contact deletion progress deprecated: true description: '' operationId: get-bulk-contact-deletion-progress tags: - Email contacts parameters: - name: deletionRequestId in: path description: The deletion request id returned from a previously called bulk contact deletion request required: true example: '' schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: Id: type: string examples: - 9133c58f-a756-46e1-8cff-bd90c6cdfb92 Status: type: string examples: - Completed examples: Result: summary: Result value: Id: 9133c58f-a756-46e1-8cff-bd90c6cdfb92 Status: Completed /v2/contacts: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 post: summary: Create contact deprecated: true description: Creates or updates a contact operationId: create-contact tags: - Email contacts parameters: [] requestBody: content: application/json: schema: type: object required: - email properties: email: type: string description: The email address of the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object examples: Request Example: value: email: john.smith@emailsim.io optInType: Single emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: POSTCODE value: N5 1DP summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: integer default: 0 examples: - 100 email: type: string examples: - john.smith@emailsim.io optInType: type: string examples: - Single emailType: type: string examples: - Html dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed examples: Result: summary: Result value: id: 100 email: john.smith@emailsim.io optInType: Single emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2016-08-01 10:09:22' - key: POSTCODE value: N5 1DP status: Subscribed get: summary: Get contacts deprecated: true description: Gets a list of all contacts in the account operationId: get-contacts tags: - Email contacts parameters: - name: withFullData in: query description: Can be set to 'true' to retrieve the contacts along with their full contact data fields required: false schema: type: boolean default: false - name: select in: query description: The number of records to select between 1 and 1000 required: false schema: type: integer format: int32 - name: skip in: query description: The numbers of records to skip in the result set required: false schema: type: integer format: int32 responses: '200': description: '200' content: application/json: schema: type: array items: type: object properties: id: type: integer default: 0 examples: - 2 email: type: string examples: - karina.plain@example.com optInType: type: string examples: - Double emailType: type: string examples: - Html dataFields: {} status: type: string examples: - Subscribed examples: Result: summary: Result value: - id: 2 email: karina.plain@example.com optInType: Double emailType: Html dataFields: null status: Subscribed - id: 3 email: erik.cryer@example.com optInType: VerifiedDouble emailType: Html dataFields: null status: Subscribed - id: 5 email: darryl.netherland@example.com optInType: Single emailType: PlainText dataFields: null status: Subscribed /v2/contacts/with-consent: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 post: summary: Create contact with consent deprecated: true description: Creates or updates a contact and their consent information operationId: create-contact-with-consent tags: - Email contacts parameters: [] requestBody: content: application/json: schema: type: object required: - contact properties: contact: type: object description: The details for the contact required: - email properties: email: type: string description: The email address for the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object consentFields: type: object description: The consent fields that apply to the contact properties: fields: type: array description: The fields that apply to the contact items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object examples: Request Example: value: contact: email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP consentFields: - fields: - key: TEXT value: Your consent text goes here. - key: DATETIMECONSENTED value: '2020-01-01 09:40:18.527000+00:00' - key: URL value: http://www.example.com/signup - key: IPADDRESS value: 127.0.0.1 - key: USERAGENT value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: contact: type: object properties: id: type: integer default: 0 examples: - 1 email: type: string examples: - john.smith@emailsim.io optInType: type: string examples: - Unknown emailType: type: string examples: - Html dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed consentFields: type: array items: type: object properties: id: {} fields: type: array items: type: object properties: key: type: string examples: - TEXT value: type: string examples: - Yes, I would like to receive a monthly newsletter examples: Result: summary: Result value: contact: id: 1 email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP status: Subscribed consentFields: - id: null fields: - key: TEXT value: Yes, I would like to receive a monthly newsletter - key: DATETIMECONSENTED value: '2020-01-01 09:40:18.527000+00:00' - key: URL value: http://www.example.com/signup - key: IPADDRESS value: 127.0.0.1 - key: USERAGENT value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 /v2/contacts/with-consent-and-preferences: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 post: summary: Create contact with consent and preferences deprecated: true description: Creates or updates a contact with consent data and marketing preferences operationId: create-contact-with-consent-and-preferences tags: - Email contacts parameters: [] requestBody: content: application/json: schema: type: object required: - contact properties: contact: type: object description: The details for the contact required: - email properties: email: type: string description: The email address for the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object consentFields: type: array description: The consent fields that apply to the contact items: properties: fields: type: array description: The fields that apply to the contact items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object type: object preferences: type: array description: The marketing preferences to be applied items: properties: id: type: integer description: The id of the preference or preference category format: int32 isPreference: type: boolean description: True if this is a preference value or false if the ID refers to a preference category preferences: type: array description: The preference values to set in the category. Only supply if isPreference is false, and therefore referring to a preference category items: properties: id: type: integer description: The id of the preference format: int32 isPreference: type: boolean description: Boolean indicating if this is preference value or group of preference values isOptedIn: type: boolean description: Whether the contact is opted into this preference or not required: - id - isPreference - isOptedIn type: object isOptedIn: type: boolean description: Whether the contact is opted in or out of the preference required: - id - isPreference type: object examples: Request Example: value: contact: email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP consentFields: - fields: - key: consenttext value: Your consent text goes here. - key: consentdatetime value: '2020-01-01 09:40:18.527000+00:00' - key: consenturl value: http://www.example.com/signup - key: consentip value: 127.0.0.1 - key: consentuseragent value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 preferences: - id: 1 isPreference: false preferences: - id: 2 isPreference: true isOptedIn: true - id: 3 isPreference: true isOptedIn: false - id: 4 isPreference: true isOptedIn: true summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: {} examples: Result: summary: Result value: '{ "contact": { "id": 1, "email": "john.smith@emailsim.io", "optInType": "Unknown", "emailType": "Html", "dataFields": [ { "key": "FIRSTNAME", "value": "John" }, { "key": "FULLNAME", "value": "John Smith" }, { "key": "GENDER", "value": "Male" }, { "key": "LASTNAME", "value": "Smith" }, { "key": "LASTSUBSCRIBED", "value": "2020-01-01T09:40:18.527Z" }, { "key": "POSTCODE", "value": "N5 1DP" } ], "status": "Subscribed" }, "consentFields": [ { "id": null, "fields": [ { "key": "TEXT", "value": "Yes, I would like to receive a monthly newsletter" }, { "key": "DATETIMECONSENTED", "value": "2020-01-01T09:40:18.527Z" }, { "key": "URL", "value": "http://www.example.com/signup" }, { "key": "IPADDRESS", "value": "127.0.0.1" }, { "key": "USERAGENT", "value": "Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36" } ] } ], "preferences": [ { "id": 1, "publicName": "test category", "privateName": "test category", "isPreference": false, "order": "0", "isPublic": true, "categoryId": 0, "preferenceCount": 2, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "preferences": [ { "id": 2, "publicName": "test preference", "privateName": "test preference", "isPreference": true, "order": "0", "isPublic": true, "categoryId": 1, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false }, { "id": 3, "publicName": "test preference 2", "privateName": "test preference 2", "isPreference": true, "order": "1", "isPublic": true, "categoryId": 1, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false } ], { "id": 4, "publicName": "test preference 3", "privateName": "test preference 3", "isPreference": true, "order": "1", "isPublic": false, "categoryId": 0, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false } } ] }' /v2/contacts/import-collection: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 post: summary: Bulk import contacts collection deprecated: true description: Bulk creates, or bulk updates, contacts from JSON operationId: bulk-import-contacts-collection tags: - Email contacts parameters: [] requestBody: content: application/json: schema: type: object required: - addressBookIds - contacts properties: addressBookIds: type: array description: If specified is the numeric ids for the address books you want to add the contacts to. items: type: integer format: int32 mergeOption: type: integer description: 'Set the behavior of how the new data should be merged into existing contacts. Overwrite: 0 , Only overwrite if not empty: 1 ,Only overwrite if contact data not populated: 2' format: int32 contacts: type: array description: The contacts to import items: properties: id: type: integer description: The numeric id for a contact format: int32 email: type: string description: The email address of the contact optInType: type: string description: The opt-in type of the contact. default: Unknown enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: The contacts data fields; the key names should match those used in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object consentFields: type: array description: Each ConsentInsight data record is a key-value pair items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object type: object examples: Request Example: value: addressBookIds: - 123 - 456 mergeOption: 0 contacts: - email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP - key: Preference:Marketing>Offers value: 'True' consentFields: - key: consenttext value: Your consent text goes here. - key: consentdatetime value: '2020-01-01 09:40:18.527000+00:00' - key: consenturl value: http://www.example.com/signup - key: consentip value: 127.0.0.1 - key: consentuseragent value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 summary: Request Example responses: '202': description: '202' content: application/json: schema: type: object properties: id: type: string examples: - af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: type: string examples: - NotFinished examples: Result: summary: Result value: id: af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: NotFinished /v2/contacts/import: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 post: summary: Bulk import contacts deprecated: true description: Bulk creates, or bulk updates, contacts from a file operationId: bulk-import-contacts tags: - Email contacts parameters: [] requestBody: content: application/json: schema: type: object required: - filename - data properties: filename: type: string description: The filename of the file being uploaded data: type: string description: The [base64](https://en.wikipedia.org/wiki/Base64) data for the file responses: '202': description: '202' content: application/json: schema: type: object properties: id: type: string examples: - af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: type: string examples: - NotFinished examples: Result: summary: Result value: id: af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: NotFinished x-readme: code-samples: - language: text code: 'Email,Firstname,Lastname,Postcode,Customfield_1,Customfield_2 user1@example.com,Bob,Smith,LXS123,Yes,100 user2@example.com,Frank,Smith,LXS121,No,200 user3@example.com,Sarah,Smith,LXS124,Yes,300' name: CSV Example samples-languages: - text /v2/contacts/import/{id}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact import status deprecated: true description: Gets the import status of a previously started contact import operationId: get-contact-import-status tags: - Email contacts parameters: - name: id in: path description: The id of the import required: true example: '' schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string examples: - af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: type: string examples: - Finished examples: Result: summary: Result value: id: af4ac4bc-e1e7-4817-8a66-73fb59e91ce6 status: Finished /v2/contacts/import/{id}/report: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact import report deprecated: true description: Gets a report with statistics about what was successfully imported, and what was unable to be imported operationId: get-contact-import-report tags: - Email contacts parameters: - name: id in: path description: The id of the import required: true example: '' schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: newContacts: type: integer default: 0 examples: - 10 updatedContacts: type: integer default: 0 examples: - 14 globallySuppressed: type: integer default: 0 examples: - 5 invalidEntries: type: integer default: 0 examples: - 7 duplicateEmails: type: integer default: 0 examples: - 3 blocked: type: integer default: 0 examples: - 1 unsubscribed: type: integer default: 0 examples: - 13 hardBounced: type: integer default: 0 examples: - 6 softBounced: type: integer default: 0 examples: - 12 ispComplaints: type: integer default: 0 examples: - 8 mailBlocked: type: integer default: 0 examples: - 9 domainSuppressed: type: integer default: 0 examples: - 2 pendingDoubleOptin: type: integer default: 0 examples: - 11 failures: type: integer default: 0 examples: - 4 suppressedContacts: type: integer default: 0 examples: - 15 examples: Result: summary: Result value: newContacts: 10 updatedContacts: 14 globallySuppressed: 5 invalidEntries: 7 duplicateEmails: 3 blocked: 1 unsubscribed: 13 hardBounced: 6 softBounced: 12 ispComplaints: 8 mailBlocked: 9 domainSuppressed: 2 pendingDoubleOptin: 11 failures: 4 suppressedContacts: 15 /v2/contacts/import/{id}/report-faults: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact import report faults deprecated: true description: Gets all contact import records that were not successfully imported operationId: get-contact-import-report-faults tags: - Email contacts parameters: - name: id in: path description: The id of the import required: true example: '' schema: type: string responses: '200': description: '200' content: text/plain: schema: type: object properties: {} examples: Result: summary: Result value: 'Reason,email,firstname,fullname,gender,lastname,postcode Unsubscribed,karina.plain@example.com,Karina,Karina Plain,Female,Plain,123456 Duplicate,demo@apiconnector.com,Demo,Demo,Male,Demo,123456' /v2/contacts/{id}/with-consent-and-preferences: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 put: summary: Update contact with consent and preferences deprecated: true description: Updates a contact by id with their consent information and/or preferences operationId: update-contact-with-consent-1 tags: - Email contacts parameters: - name: id in: path description: The contacts unique id required: true example: 0 schema: type: integer format: int32 requestBody: content: application/json: schema: type: object required: - contact properties: contact: type: object description: The contact details required: - email properties: email: type: string description: The email address for the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object consentFields: type: array description: The consent fields that apply to the contact items: properties: fields: type: array description: The fields that apply to the contact items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object type: object preferences: type: array description: The marketing preferences to be updated items: properties: id: type: integer description: The id of the preference or preference category format: int32 isPreference: type: boolean description: True if this is a preference value or false if the ID refers to a preference category preferences: type: array description: The preference values to set in the category. Only supply if isPreference is false, and therefore referring to a preference category items: properties: id: type: integer description: The id of the preference format: int32 isPreference: type: boolean description: Boolean indicating if this is preference value or group of preference values isOptedIn: type: boolean description: Whether the contact is opted into this preference or not required: - id - isPreference - isOptedIn type: object isOptedIn: type: boolean description: Whether the contact is opted in or out of the preference required: - id - isPreference type: object examples: Request Example: value: contact: email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP consentFields: - fields: - key: consenttext value: Your consent text goes here. - key: consentdatetime value: '2020-01-01 09:40:18.527000+00:00' - key: consenturl value: http://www.example.com/signup - key: consentip value: 127.0.0.1 - key: consentuseragent value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 preferences: - id: 1 isPreference: false preferences: - id: 2 isPreference: true isOptedIn: true - id: 3 isPreference: true isOptedIn: false - id: 4 isPreference: true isOptedIn: true summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: {} examples: Result: summary: Result value: '{ "contact": { "id": 1, "email": "john.smith@emailsim.io", "optInType": "Unknown", "emailType": "Html", "dataFields": [ { "key": "FIRSTNAME", "value": "John" }, { "key": "FULLNAME", "value": "John Smith" }, { "key": "GENDER", "value": "Male" }, { "key": "LASTNAME", "value": "Smith" }, { "key": "LASTSUBSCRIBED", "value": "2020-01-01T09:40:18.527Z" }, { "key": "POSTCODE", "value": "N5 1DP" } ], "status": "Subscribed" }, "consentFields": [ { "id": null, "fields": [ { "key": "TEXT", "value": "Yes, I would like to receive a monthly newsletter" }, { "key": "DATETIMECONSENTED", "value": "2020-01-01T09:40:18.527Z" }, { "key": "URL", "value": "http://www.example.com/signup" }, { "key": "IPADDRESS", "value": "127.0.0.1" }, { "key": "USERAGENT", "value": "Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36" } ] } ], "preferences": [ { "id": 1, "publicName": "test category", "privateName": "test category", "isPreference": false, "order": "0", "isPublic": true, "categoryId": 0, "preferenceCount": 2, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "preferences": [ { "id": 2, "publicName": "test preference", "privateName": "test preference", "isPreference": true, "order": "0", "isPublic": true, "categoryId": 1, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false }, { "id": 3, "publicName": "test preference 2", "privateName": "test preference 2", "isPreference": true, "order": "1", "isPublic": true, "categoryId": 1, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false } ], { "id": 4, "publicName": "test preference 3", "privateName": "test preference 3", "isPreference": true, "order": "1", "isPublic": false, "categoryId": 0, "preferenceCount": 0, "created": "2020-01-01T09:40:18.527Z", "lastModified": "2020-01-02T09:40:18.527Z", "isOptedIn": false } } ] } ' /v2/contacts/{id}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 delete: summary: Delete contact deprecated: true description: Deletes a contact by ID operationId: delete-contact tags: - Email contacts parameters: - name: id in: path description: The id of the contact required: true example: 0 schema: type: integer format: int32 responses: '204': description: '204' content: application/json: schema: type: object properties: {} examples: Result: summary: Result value: {} put: summary: Update contact deprecated: true description: Updates a contact by id operationId: update-contact tags: - Email contacts parameters: - name: id in: path description: The contacts unique id required: true example: 0 schema: type: integer format: int32 requestBody: content: application/json: schema: type: object required: - email properties: email: type: string description: The email address of the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object examples: Request Example: value: email: john.smith@emailsim.io optInType: Double dataFields: - key: GENDER value: Male summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: integer default: 0 examples: - 100 email: type: string examples: - john.smith@emailsim.io optInType: type: string examples: - Double emailType: type: string examples: - PlainText dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed examples: Result: summary: Result value: id: 100 email: john.smith@emailsim.io optInType: Double emailType: PlainText dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: POSTCODE value: null status: Subscribed /v2/contacts/{contactIdentifier}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact deprecated: true description: Gets a contact operationId: get-contact tags: - Email contacts parameters: - name: contactIdentifier in: path description: Either the contact id or email address of the contact required: true example: '' schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: integer default: 0 examples: - 100 email: type: string examples: - john.smith@emailsim.io optInType: type: string examples: - Unknown emailType: type: string examples: - PlainText dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed examples: Result: summary: Result value: id: 100 email: john.smith@emailsim.io optInType: Unknown emailType: PlainText dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: null - key: LASTNAME value: Smith - key: POSTCODE value: null status: Subscribed /v2/contacts/{contactIdentifier}/with-consent: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact with consent deprecated: true description: Gets a contact with their consent information operationId: get-contact-with-consent tags: - Email contacts parameters: - name: contactIdentifier in: path description: Either the contact id or email address of the contact required: true example: '' schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: contact: type: object properties: id: type: integer default: 0 examples: - 1 email: type: string examples: - john.smith@example.com optInType: type: string examples: - Unknown emailType: type: string examples: - Html dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed consentFields: type: array items: type: object properties: id: type: string examples: - 26/01/2018 21:29:00 (CEXlxDq08olHcCXN08B/2Jj/AEQi5ENrQjYxi+wrlwE=) fields: type: array items: type: object properties: key: type: string examples: - TEXT value: type: string examples: - Yes, I would like to receive a monthly newsletter examples: Result: summary: Result value: contact: id: 1 email: john.smith@example.com optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP status: Subscribed consentFields: - id: 26/01/2018 21:29:00 (CEXlxDq08olHcCXN08B/2Jj/AEQi5ENrQjYxi+wrlwE=) fields: - key: TEXT value: Yes, I would like to receive a monthly newsletter - key: DATETIMECONSENTED value: '2018-01-26 21:29:00' - key: URL value: http://www.example.com/signup - key: IPADDRESS value: 127.0.0.1 - key: USERAGENT value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 - key: DATETIMECREATED value: '2020-01-01 09:40:18.527000+00:00' /v2/contacts/{id}/address-books: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contact address books deprecated: true description: Gets any address books that a contact is in operationId: get-contact-address-books tags: - Email contacts parameters: - name: id in: path description: The id of the contact required: true example: 0 schema: type: integer format: int32 - name: select in: query description: The number of records to select between 1 and 1000 required: false schema: type: integer format: int32 - name: skip in: query description: The numbers of records to skip in the result set required: false schema: type: integer format: int32 responses: '200': description: '200' content: application/json: schema: type: array items: type: object properties: id: type: integer default: 0 examples: - 1 name: type: string examples: - Address book 1 visibility: type: string examples: - Private contacts: type: integer default: 0 examples: - 5 examples: Result: summary: Result value: - id: 1 name: Address book 1 visibility: Private contacts: 5 - id: 2 name: Address book 2 visibility: Public contacts: 7 /v2/contacts/count: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get all contacts count deprecated: true description: Gets the total number of contacts in the account operationId: get-all-contacts-count tags: - Email contacts parameters: [] responses: '200': description: '200' content: text/plain: schema: type: integer default: 0 examples: - 42525 examples: Result: summary: Result value: 42525 /v2/contacts/created-since/{date}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get contacts created since date deprecated: true description: Gets a list of created contacts after a specified date operationId: get-contacts-created-since-date tags: - Email contacts parameters: - name: date in: path description: The date from which any created contacts are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime) required: true example: '' schema: type: string format: date - name: withFullData in: query description: Can be set to 'true' to retrieve the contacts along with their full contact data fields required: false schema: type: boolean default: false - name: select in: query description: The number of records to select between 1 and 1000 required: false schema: type: integer format: int32 - name: skip in: query description: The numbers of records to skip in the result set required: false schema: type: integer format: int32 responses: '200': description: '200' content: application/json: schema: type: array items: type: object properties: id: type: integer default: 0 examples: - 99 email: type: string examples: - tiffany.valverde@example.com optInType: type: string examples: - Double emailType: type: string examples: - Html dataFields: {} status: type: string examples: - Subscribed examples: Result: summary: Result value: - id: 99 email: tiffany.valverde@example.com optInType: Double emailType: Html dataFields: null status: Subscribed - id: 100 email: john.smith@example.com optInType: Single emailType: Html dataFields: null status: Subscribed /v2/contacts/modified-since/{date}: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 get: summary: Get modified contacts since date deprecated: true description: Gets a list of modified contacts after a specified date operationId: get-modified-contacts-since-date tags: - Email contacts parameters: - name: date in: path description: The date from which any modified contacts are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime) required: true example: '' schema: type: string format: date - name: withFullData in: query description: Can be set to 'true' to retrieve the contacts along with their full contact data fields required: false schema: type: boolean default: false - name: select in: query description: The number of records to select between 1 and 1000 required: false schema: type: integer format: int32 - name: skip in: query description: The numbers of records to skip in the result set required: false schema: type: integer format: int32 responses: '200': description: '200' content: application/json: schema: type: array items: type: object properties: id: type: integer default: 0 examples: - 99 email: type: string examples: - tiffany.valverde@example.com optInType: type: string examples: - Double emailType: type: string examples: - Html dataFields: {} status: type: string examples: - Subscribed examples: Result: summary: Result value: - id: 99 email: tiffany.valverde@example.com optInType: Double emailType: Html dataFields: null status: Subscribed - id: 100 email: john.smith@example.com optInType: Single emailType: Html dataFields: null status: Subscribed /v2/contacts/{id}/with-consent: parameters: - in: header name: x-ddg-integration-token required: false description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here. schema: type: string pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/ example: 5a96bc79-19a7-4544-973b-e2da0c9136f9 put: summary: Update contact with consent deprecated: true description: Updates a contact by id with their consent information operationId: update-contact-with-consent tags: - Email contacts parameters: - name: id in: path description: The contacts unique id required: true example: 0 schema: type: integer format: int32 requestBody: content: application/json: schema: type: object required: - contact properties: contact: type: object description: The contact details required: - email properties: email: type: string description: The email address for the contact optInType: type: string description: The opt-in type of the contact enum: - Unknown - Single - Double - VerifiedDouble emailType: type: string description: The email type of the contact enum: - PlainText - Html dataFields: type: array description: Each contact data field is a key-value pair; the key is a string matching the data field name in Dotdigital items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object consentFields: type: array description: The consent fields that apply to the contact items: properties: fields: type: array description: The fields that apply to the contact items: properties: key: type: string description: The key name value: type: string description: The value associated with the key required: - key - value type: object type: object examples: Request Example: value: contact: email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: POSTCODE value: N5 1DP consentFields: - fields: - key: TEXT value: Your consent text goes here. - key: DATETIMECONSENTED value: '2020-01-01 09:40:18.527000+00:00' - key: URL value: http://www.example.com/signup - key: IPADDRESS value: 127.0.0.1 - key: USERAGENT value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36 summary: Request Example responses: '201': description: '201' content: application/json: schema: type: object properties: contact: type: object properties: id: type: integer default: 0 examples: - 1 email: type: string examples: - john.smith@emailsim.io optInType: type: string examples: - Unknown emailType: type: string examples: - Html dataFields: type: array items: type: object properties: key: type: string examples: - FIRSTNAME value: type: string examples: - John status: type: string examples: - Subscribed consentFields: type: array items: type: object properties: id: {} fields: type: array items: type: object properties: key: type: string examples: - TEXT value: type: string examples: - Yes, I would like to receive a monthly newsletter examples: Result: summary: Result value: contact: id: 1 email: john.smith@emailsim.io optInType: Unknown emailType: Html dataFields: - key: FIRSTNAME value: John - key: FULLNAME value: John Smith - key: GENDER value: Male - key: LASTNAME value: Smith - key: LASTSUBSCRIBED value: '2020-01-01 09:40:18.527000+00:00' - key: POSTCODE value: N5 1DP status: Subscribed consentFields: - id: null fields: - key: TEXT value: Yes, I would like to receive a monthly newsletter - key: DATETIMECONSENTED value: '2020-01-01 09:40:18.527000+00:00' - key: URL value: http://www.example.com/signup - key: IPADDRESS value: 127.0.0.1 - key: USERAGENT value: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36