Getting Started with Engage API
1) User Creation
If you do not have an API (Or hybrid) User account, one must be created. Any user who has user creation permission can create an API user account.
- In Mapp Engage, select User Management > System User > System User
- In the System Users Screen, Select Create
- Under the Type drop-down, select API User
- Enter your API user's contact details, and make sure the Role is set to Client Administrator.
- Select Save
Please note, that while hybrid users can be used for API accounts, we do not recommend this approach. The separation of API and User Interface users and their activities in your company's account makes it much easier to see who exactly made the changes.
For more information on this, please see New System User.
2) Sending A Request
Authorization & Permissions
Both SOAP and REST API use HTTP basic authentication method that does not require cookies or session tokens. For this reason, there are no explicit login and logout methods.
Instead, the authorization header (encoded in Base64) must be included in each API request. You can create this yourself based on the username and password of the API User in your specific platform.
The example header for 'j.mcexample@example.com' user and 'ThisizAstr0ngPswrd!!_' password is the following:
Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb20gcHc6IFRoaXNpekFzdHIwbmdQc3dyZCEhXw==
Only API and Hybrid user credentials can be used to build this Basic Auth Header to be used in the API call.
Host header
Users connecting to the Mapp Engage API should ensure that their web service clients correctly add or include the Host header in the HTTP header. The domain name sent in the HTTP header must be identical to the web service URL you are connecting to. Our web services require that the host header value be set as this will be used along and in parallel with the requested URL when connecting to our servers.
Host: yourdomain.com
Without this host header, there could be issues when connecting to the correct service and server, and it could also trip our anti-intrusion systems.
In the example below, not only is the HTTP REST request being requested by GET to the domain cook.shortest-route.com but in the HTTP header, the corresponding virtual host is also specified in the "Host" field.
GET https://yourdomain.com/api/rest/v9/contact/anonymize?contactId=12345678901¬ificationRecipient=system.user@example.tld HTTP/1.1
Host: yousdomain.com.com
User-Agent: Rest Webservice Test Client 1.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br
Content-Type: application/json
Authorization: Basic QXNJZklXb3VsZFB1dEFSZWFsVXNlcm5hbWVIZXJlOlRoaXNJc05vdEFQYXNzd29yZA==
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Domains
API calls are grouped within functional test domains. A full list of domains and calls can be found in our Swagger documentation. You can also find the domains below.
REST | SOAP | Description |
---|---|---|
async | async | Contains methods for response queue. |
automation | automation | Contains methods for automation in Mapp Engage. |
blacklist | blacklist | Contains methods to manage the system and group blacklists. |
cms | cms | Contains methods to manage messages stored in the CMS. |
contact | contact | Contains methods for contact management. |
user | user | Contains more methods for contact management. |
content | content | Contains methods to manage elements in the Content Store. |
draftmessage | draftmessage | Contains methods for working with messages saved as a draft. |
group | group | Contains all group-related methods. |
landingpage | landingpage | Contains methods to manage landing pages. |
membership | membership | Contains methods to manage group memberships. |
message | message | Contains methods to manage email and SMS messages. |
meta | meta | Contains methods that define your system. |
mobile | n/a | The mobile domain contains methods to manage approx properties |
preparedmessage | preparedmessage | A prepared message is a saved message assigned to a group. |
process | process | Contains methods to interact with a process in Mapp Engage. |
relatedData | relateddata | Contains methods to manage records stored in Related Data. |
system | system | Contains methods about the current version of the system. |
systemuser | systemuser | Contains methods related to the system user. |
usagestatistics | usagestatistics | Contains methods pertaining to usage statistics. |
Versioning
Contact Mapp Technical Support to confirm if you have the latest version. At the moment this is v19.
3) Testing
Here are some outside tools which may help you get started using API:
Tool | Link |
---|---|
SoapUI | An open-source web service testing tool |
Postman | Download and install |
To setup REST project | Example REST project |
To setup SOAP project | Example SOAP project |
To setup Control XML project | Example Control XML project |
To setup SOAP 1.0 (deprecated) | Example SOAP 1.0 |
Related Topics
Engage API implementation and error-handling recommendations