Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Email contacts API
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.'
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: []
tags:
- name: Email contacts
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
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotdigital/refs/heads/main/openapi/dotdigital-email-contacts-api-openapi.yml