Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Mapp Engage public User API
version: '1'
description: 'Mapp Engage REST API (REST 2.0, incremental version v19). Assembled verbatim from the per-operation OpenAPI fragments Mapp publishes on each endpoint page of https://docs.mapp.com/apidocs/. The base URL is tenant-specific: take your Mapp Engage login host and append /api/rest/v19.'
contact:
name: Mapp Technical Support
url: https://mapp.com/tech-support/
servers:
- url: /api/rest/v19
security:
- basicAuth: []
tags:
- name: User
paths:
/user/create:
post:
tags:
- User
summary: Create a user
description: 'Creates a new user. Requires either an email or a mobile number since these fields are used as the unique user identifier in the system.
Request body example:
[
{"name" : "user.lastname", "value" : "Smith"},
{"name" : "DateOfBirth", "value" : "1970-05-05"},
{"name" : "ISOlanguagecode", "value" : "fr"},
{"name": "user.ISOCountryCode", "value": "FR"}
]'
operationId: createUser
parameters:
- name: email
in: query
description: Email of the user
required: true
schema:
type: string
- name: mobileNumber
in: query
description: Mobile number of the user
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: User with email does already exist. / One of the parameters 'email' or 'mobileNumber' must not be empty.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/deleteByEmail:
delete:
tags:
- User
summary: Delete a user by email
description: Deletes the user identified by the email address.
operationId: deleteByEmail
parameters:
- name: email
in: query
description: Email of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: Parameter 'email' is mandatory, but missing or incorrect.
/user/deleteByMobileNumber:
delete:
tags:
- User
summary: Delete a user by mobile number
description: Deletes the user identified by the mobile number.
operationId: deleteByMobileNumber
parameters:
- name: mobileNumber
in: query
description: Mobile number of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: Parameter 'mobileNumber' is mandatory, but missing or incorrect.
/user/delete:
delete:
tags:
- User
summary: Delete a user
description: Deletes the user identified by the specified ID
operationId: deleteUser
parameters:
- name: userId
in: query
description: User id
required: false
schema:
type: integer
format: int64
responses:
'204':
description: ''
'400':
description: Parameter 'userID' is mandatory, but missing or incorrect.
'404':
description: Not Found
/user/getByEmail:
get:
tags:
- User
summary: Get a user by email
description: Returns user data from the profile identified by the provided email address. This includes the unique user ID, email address, mobile number, and profile identifier value.
operationId: getUserByEmail
parameters:
- name: email
in: query
description: Email of the user
required: true
schema:
type: string
responses:
'200':
description: 'Example response:<br><br>{<br> "id": 18067305231,<br> "email": "test@test.com",<br> "mobileNumber": null,<br> "identifier": null<br>}'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: Parameter 'email' is not a valid email address. / User with email does not exist.
/user/getByIdentifier:
get:
tags:
- User
summary: Get a user by identifier
description: Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned.
operationId: getByIdentifier
parameters:
- name: identifier
in: query
description: Identifier of the user
required: true
schema:
type: string
responses:
'200':
description: 'Example response:<br><br>{<br> "id": 18067305231,<br> "email": "test@test.com",<br> "mobileNumber": null,<br> "identifier": null<br>}'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: ''
/user/getByMobileNumber:
get:
tags:
- User
summary: Get a user by mobile number
description: Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned
operationId: getByMobileNumber
parameters:
- name: mobileNumber
in: query
description: Mobile number of the user
required: true
schema:
type: string
responses:
'200':
description: 'Example response: <br>{<br> "id": 18067305231,<br> "email": "test@test.com",<br> "mobileNumber": null,<br> "identifier": null<br>}'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: User with mobile number does not exist. / Parameter 'mobileNumber' is not a valid phone number.
/user/getMessageHistory:
get:
tags:
- User
summary: Get a user's message history
description: 'Retrieves the message history for a recipient for a set time frame.
The maximum time frame is 31 days. The maximum number of messages returned is 5000. sendDate is presented as Datetim'
operationId: getMessageHistory
parameters:
- name: userId
in: query
description: User id
required: false
schema:
type: integer
format: int64
- name: fromDate
in: query
description: Start date of time frame in ISO 8601 date time format.
required: false
schema:
type: string
- name: toDate
in: query
description: End date of time frame in ISO 8601 date time format.
required: false
schema:
type: string
responses:
'200':
description: 'Example response: <br>[<br> {<br> "messageID": [354476555],<br> "externalTransactionId": {},<br> "externalMessageID": {},<br> "messageName": ["Test"],<br> "messageSubject": ["Test"],<br> "groupId": [353599854],<br> "groupName": ["Test"],<br> "groupEmail": ["test@test.com"],<br> "sendDate": [1491216661590],<br> "messageType": ["single"],<br> "status": ["Sent"],<br> "clicked": [true],<br> "opened": [false]<br> }<br>]'
content:
application/json:
schema:
type: array
items:
type: object
application/xml:
schema:
type: array
items:
type: object
'400':
description: Parameter 'userID' is mandatory, but missing or incorrect./ user with the given id does not exist.
/user/getProfileByEmail:
get:
tags:
- User
summary: Get a user's profile by email
description: Returns the user's profile, this is identified by the email address.
operationId: getProfileByEmail
parameters:
- name: email
in: query
description: Email of the user
required: true
schema:
type: string
responses:
'200':
description: 'Example response: <br>[{<br> "name": "user.ISOLanguageCode",<br> "value": "it" }, {<br> "name": "user.Email",<br> "value": "test@test.com" }, {<br> "name": "user.EmailDomain",<br> "value": "test.de" }, {<br> "name": "user.LastName",<br> "value": "Cloned" }, {<br> "name": "user.FirstName",<br> "value": "Test" }, {<br> "name": "user.ISOCountryCode",<br> "value": "IT" }<br>}]'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: Parameter 'email' is mandatory, but missing or incorrect./ user with the given email does not exist.
/user/getProfileByMobileNumber:
get:
tags:
- User
summary: Get a user's profile by mobile number
description: Returns the user's profile, identified by the mobile number
operationId: getProfileByMobileNumber
parameters:
- name: mobileNumber
in: query
description: Mobile number of the user
required: true
schema:
type: string
responses:
'200':
description: 'Example response: <br>{<br> "name": "user.ISOLanguageCode",<br> "value": "it" }, {<br> "name": "user.Email",<br> "value": "test@test.com" }, {<br> "name": "user.EmailDomain",<br> "value": "test.de" }, {<br> "name": "user.LastName",<br> "value": "Cloned" }, {<br> "name": "user.FirstName",<br> "value": "Test" }, {<br> "name": "user.ISOCountryCode",<br> "value": "IT" }<br>}'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: Parameter 'mobileNumber' is mandatory, but missing or incorrect./ user with the given mobileNumber does not exist.
/user/getProfile:
get:
tags:
- User
summary: Get a user's profile
description: Returns the user's profile (only attributes with a value are shown). The profile consists of attributes that contain user data. All attributes can be accessed system-wide.
operationId: getProfile
parameters:
- name: userId
in: query
description: ID of the user
required: true
schema:
type: integer
format: int64
responses:
'200':
description: 'Example response: <br>[{<br> "name": "user.ISOLanguageCode",<br> "value": "it" }, {<br> "name": "user.Email",<br> "value": "test@test.com" }, {<br> "name": "user.EmailDomain",<br> "value": "test.de" }, {<br> "name": "user.LastName",<br> "value": "Cloned" }, {<br> "name": "user.FirstName",<br> "value": "Test" }, {<br> "name": "user.ISOCountryCode",<br> "value": "IT" }<br>}]'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: Parameter 'userID' is mandatory, but missing or incorrect./ user with the given id does not exist.
'404':
description: 'Error response: {<br>"errorActor": "CLIENT",<br>"errorCode": "INVALID_REQUEST",<br>"message": "Not Found"<br>}'
/user/get:
get:
tags:
- User
summary: Get a user
description: Returns the user identified by the specified user ID.
operationId: getUser
parameters:
- name: userId
in: query
description: ID of the user
required: true
schema:
type: integer
format: int64
responses:
'200':
description: 'Example response: <br>{<br> "id": 18067305231,<br> "email": "test@test.com",<br> "mobileNumber": null,<br> "identifier": null<br>}'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
'400':
description: Parameter 'userID' is mandatory, but missing or incorrect./ user with the given id does not exist.Error response
'404':
description: 'Error response: {<br>"errorActor": "CLIENT",<br>"errorCode": "INVALID_REQUEST",<br>"message": "Not Found"<br>}'
/user/replaceProfileByEmail:
post:
tags:
- User
summary: Replace a user's profile by email
description: 'Replaces all attribute values for a specific user. All attribute values that are transmitted with the method are added and replace any existing values.
Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).
Request body example:
[
{"name" : "user.firstname", "value" : "FirstName"},
{"name" : "user.lastname", "value" : "LastName"}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: replaceProfileByEmail
parameters:
- name: email
in: query
description: Email of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: Parameter 'email' is mandatory, but missing or incorrect./ user with the given email does not exist.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/replaceProfileByMobileNumber:
post:
tags:
- User
summary: Replace a user's profile by mobile number
description: 'Replaces all attribute values for a specific user. All attribute values that are transmitted with the method are added and replace any existing values.
Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).
Request body example:
[
{"name" : "user.firstname", "value" : "FirstName"},
{"name" : "user.lastname", "value" : "LastName"}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: replaceProfileByMobileNumber
parameters:
- name: mobileNumber
in: query
description: Mobile number of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: Parameter 'mobileNumber' is mandatory, but missing or incorrect./ user with the given mobileNumber does not exist.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/replaceProfile:
post:
tags:
- User
summary: Replace a user's profile
description: 'Replaces all attribute values for a specific user. All attribute values that are transmitted with the method are added and replace any existing values.
Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).
Request body example:
[
{"name" : "user.firstname", "value" : "John"},
{"name" : "user.lastname", "value" : "Smith"}
]
Request body example - erase mobile number:
[
{"name" : "user.MobileNumber", "value" : null}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: replaceProfile
parameters:
- name: userId
in: query
description: ID of the user
required: false
schema:
type: integer
format: int64
responses:
'204':
description: ''
'400':
description: Parameter 'userID' is mandatory, but missing or incorrect./ user with the given id does not exist.
'404':
description: Not Found
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/updateProfileByEmail:
post:
tags:
- User
summary: Update a user's profile by email
description: 'Updates a user identified via email. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).
Request body example:
[
{"name" : "user.firstname", "value" : "John"},
{"name" : "user.lastname", "value" : "Smith"}
]
Request body example - erase mobile number:
[
{"name" : "user.MobileNumber", "value" : null}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: updateProfileByEmail
parameters:
- name: email
in: query
description: Email of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: 'Email address not existing in the Engage system provided as a parameter.<br><br>Example:<br><pre>{<br> "errorActor": "CLIENT",<br> "errorCode": "NO_SUCH_OBJECT",<br> "message": "User with email=no.email@example.com does not exist.",<br> "objectType": "User",<br> "propertyName": "email",<br> "propertyValue": "no.email@example.com"<br>}</pre>'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/updateProfileByMobileNumber:
post:
tags:
- User
summary: Update a user's profile by mobile number
description: 'Updates a user identified via mobile number. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).
Request body example:
[
{"name" : "user.firstname", "value" : "FirstName"},
{"name" : "user.lastname", "value" : "LastName"}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: updateProfileByMobileNumber
parameters:
- name: mobileNumber
in: query
description: Mobile number of the user
required: false
schema:
type: string
responses:
'204':
description: ''
'400':
description: Parameter 'mobileNumber' is mandatory, but missing or incorrect./ user with the given mobileNumber does not exist.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
/user/updateProfile:
post:
tags:
- User
summary: Update a user's profile
description: 'Updates the user''s profile with the information saved in the attribute list. Attributes that are not mentioned are not changed.
Note: There is also a user replaceProfile method to
1) change the entire profile of a user and
2) to delete attribute values if the attribute is not mentioned for the user.
Request body example:
[
{"name" : "user.firstname", "value" : "John"},
{"name" : "user.lastname", "value" : "Smith"},
{"name": "user.ISOCountryCode", "value": "FR"}
]
Request body example - erase mobile number:
[
{"name" : "user.MobileNumber", "value" : null}
]
Maximum character lengths for standard attribute values:
FirstName: 50
LastName: 50
Nickname: 20
ZipCode: 10
Identifier: 2000
Photo: 2000
Other standard attributes (Email, MobileNumber, ISOCountryCode, ISOLanguageCode, TimeZone, Title, DateOfBirth) are validated by format/enum, not by length. Note that Email is stored in a column of length 129.
Custom attribute values are limited to 2000 characters.
Values exceeding these limits are rejected with HTTP 400 (INVALID_PARAMETER); during contact import, oversized values are silently truncated.'
operationId: updateProfile
parameters:
- name: userId
in: query
description: ID of the user
required: false
schema:
type: integer
format: int64
responses:
'204':
description: ''
'400':
description: Parameter 'userId' is mandatory but no value was specified. / The request didn't contain a request entity. / User with id does not exist.
'404':
description: Parameter 'userID' is mandatory, but missing or incorrect./ user with the given id does not exist.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attribute'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication with a Mapp Engage system user of type API (or Hybrid).
x-apievangelist-provenance:
method: searched
generated: '2026-08-12'
source: https://docs.mapp.com/apidocs/ (per-endpoint OpenAPI fragments)
note: Union of the OpenAPI JSON fragments Mapp publishes on each endpoint page. Mapp does not serve one consolidated document at a public URL; the tenant-served Swagger lives at https://<your-engage-host>/apidoc/swagger.json and requires a tenant. Operation bodies, parameters, responses, tags, summaries and descriptions are verbatim from Mapp. The swagger/basePath/schemes/securityDefinitions envelope is added by API Evangelist from the published Getting Started guide; no operation content was authored.
duplicate_operation_ids_suffixed: 30