Rest API v1.0

Common

Basics

The base-URL is https://api.maileon.com/1.0/

Make sure to use HTTPS. If you have trouble with the certificate fix the problems. In some older examples HTTP might have been used but this is not allowed any longer, you will get an error status code 403.

General
→ Security Mechanisms
→ API Logs
→ Using MergeTags in Mailings
→ Frequently Asked Questions

Using the API
→ Authentication
→ Mediatypes
→ Data Compression
→ Pagination
→ HTTP Status Codes
→ Guidelines for XML Documents

Starting with Development
→ Check our Guidelines

Ping

Goal of this resource is to provide a convenient API test functionality. It should allow the developer to easily verify the correct setup including the proper permissions for the respective API key.
Resources

Name	Method / URL
GET Test	GET https://api.maileon.com/1.0/ping
POST Test	POST https://api.maileon.com/1.0/ping
PUT Test	PUT https://api.maileon.com/1.0/ping
DELETE Test	DELETE https://api.maileon.com/1.0/ping

Contacts

Resources

General

Name	Method / URL
Delete All Contacts	DELETE https://api.maileon.com/1.0/contacts
Get Count Contacts	GET GET https://api.maileon.com/1.0/contacts/count
Get Contacts	GET https://api.maileon.com/1.0/contacts
Get Contacts By Filter Id	GET https://api.maileon.com/1.0/contacts/filter/{contactFilterId}
Count Contacts By Filter Id	GET https://api.maileon.com/1.0/contacts/filter/{contactFilterId}/count
Count Active Contacts By Filter Id	GET https://api.maileon.com/1.0/contacts/filter/{contactFilterId}/count/active
Get Blocked Contacts	GET https://api.maileon.com/1.0/contacts/contact/blocked
Synchronize Contacts	POST https://api.maileon.com/1.0/contacts
Create Custom Field	POST https://api.maileon.com/1.0/contacts/fields/custom/:field
Get Custom Fields	GET https://api.maileon.com/1.0/contacts/fields/custom
Delete Custom Field	DELETE https://api.maileon.com/1.0/contacts/fields/custom/:field
Delete Standard Field Values	DELETE https://api.maileon.com/1.0/contacts/fields/standard/:field/values
Delete Custom Field Values	DELETE https://api.maileon.com/1.0/contacts/fields/custom/:field/values
Rename Custom Field	PUT https://api.maileon.com/1.0/contacts/fields/custom/:oldname/:newname

Contact Preferences

Name	Method / URL
Get Contact Preference Categories	GET https://api.maileon.com/1.0/contacts/preference_categories
Create Contact Preference Category	POST https://api.maileon.com/1.0/contacts/preference_categories
Get Contact Preference Category by Name	GET https://api.maileon.com/1.0/contacts/preference_categories/:categoryName
Update Contact Preference Category	PUT https://api.maileon.com/1.0/contacts/preference_categories/:categoryName
Delete Contact Preference Category	DELETE https://api.maileon.com/1.0/contacts/preference_categories/:categoryName
Get Preferences of Contact Preferences Category	GET https://api.maileon.com/1.0/contacts/preference_categories/:categoryName/preferences
Create Contact Preference	POST https://api.maileon.com/1.0/contacts/preference_categories/:categoryName/preferences
Update Contact Preference	PUT https://api.maileon.com/1.0/contacts/preference_categories/:categoryName/preferences/:preferenceName
Delete Contact Preference	DELETE https://api.maileon.com/1.0/contacts/preference_categories/:categoryName/preferences/:preferenceName
Get Contact Preference	GET https://api.maileon.com/1.0/contacts/preference_categories/:categoryName/preferences/:preferenceName

By Maileon ID

Name	Method / URL
Delete Contact By Maileon ID	DELETE https://api.maileon.com/1.0/contacts/contact
Get Contact By Maileon ID	GET https://api.maileon.com/1.0/contacts/contact
Unsubscribe Contact By Maileon ID	DELETE https://api.maileon.com/1.0/contacts/contact/unsubscribe
Update Contact By Maileon ID	PUT https://api.maileon.com/1.0/contacts/contact
Add Unsubscription Reason to Already Unsubscribed Contact	PUT https://api.maileon.com/1.0/contacts/contact/unsubscribe/reasons

By Email-Address

Name	Method / URL
Create Contact	POST https://api.maileon.com/1.0/contacts/email/:email
Create Contact (JSON)	POST https://api.maileon.com/1.0/contacts/email/:email
Update Contact By Email	PUT https://api.maileon.com/1.0/contacts/email/:email
Delete Contacts By Email	DELETE https://api.maileon.com/1.0/contacts/email/:email
Get Contact By Email	GET https://api.maileon.com/1.0/contacts/email/:email
Get Contacts By Email	GET https://api.maileon.com/1.0/contacts/emails/:email
Unsubscribe Contacts By Email	DELETE https://api.maileon.com/1.0/contacts/email/:email/unsubscribe
Get Unsubscription-Marker	GET https://api.maileon.com/1.0/contacts/email/:email/unsubscription
Set Unsubscription-Marker	PUT https://api.maileon.com/1.0/contacts/email/:email/unsubscription
Delete Unsubscription-Marker	DELETE https://api.maileon.com/1.0/contacts/email/:email/unsubscription

By External-ID

Name	Method / URL
Create Contact By External Id	POST https://api.maileon.com/1.0/contacts/externalid/:value
Create Contact By External Id (JSON)	POST https://api.maileon.com/1.0/contacts/externalid/:value
Update Contact By External Id	PUT https://api.maileon.com/1.0/contacts/externalid/:value
Delete Contacts By External Id	DELETE https://api.maileon.com/1.0/contacts/externalid/:value
Get Contacts By External Id	GET https://api.maileon.com/1.0/contacts/externalid/:value
Unsubscribe Contacts By External ID	DELETE https://api.maileon.com/1.0/contacts/externalId/:value/unsubscribe

Appendices
→ Contacts
→ Standard Contact Fields
→ Custom Contact Fields
→ Synchronize Contacts Error Codes

Contactfilters

Resources

Name	Method / URL
Get Count Contactfilters	GET https://api.maileon.com/1.0/contactfilters/count
Get Contactfilters	GET https://api.maileon.com/1.0/contactfilters
Get Contactfilter Properties Properties	GET https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}
Create Contactfilter	POST https://api.maileon.com/1.0/contactfilters/v2
Update Contactfilter Properties	PUT https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}
Update Contactfilter	PUT https://api.maileon.com/1.0/contactfilters/v2/contactfilter/{:contactFilterId}
Delete Contactfilter	DELETE https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}
Refresh Contactfilter-Contacts	GET https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}/refresh
Get Contacts By Filter Id (See Contacts Resource)	GET https://api.maileon.com/1.0/contacts/filter/{contactFilterId}
Get Contactfilter lock state	GET https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}/lock
Set Contactfilter lock state	POST https://api.maileon.com/1.0/contactfilters/contactfilter/{contactFilterId}/lock

Appendices
→ Contactfilter XML structure

Targetgroups

Resources

Name	Method / URL
Get Targetgroup count	GET https://api.maileon.com/1.0/targetgroups/count
Get Targetgroups	GET https://api.maileon.com/1.0/targetgroups
Create Targetgroup	POST https://api.maileon.com/1.0/targetgroups
Get Targetgroup	GET https://api.maileon.com/1.0/targetgroups/targetgroup/{groupId}
Delete Targetgroup	DELETE https://api.maileon.com/1.0/targetgroups/targetgroup/{groupId}

Appendices
→ Targetgroup XML structure

Reports

Please be aware, that report data can not be retrieved, if older than two years.

Resources

Name	Method / URL
Get Opens	GET https://api.maileon.com/1.0/reports/opens
Get Unique Opens	GET https://api.maileon.com/1.0/reports/opens/unique
Get Clicks	GET https://api.maileon.com/1.0/reports/clicks
Get Unique Clicks	GET https://api.maileon.com/1.0/reports/clicks/unique
Get Bounces	GET https://api.maileon.com/1.0/reports/bounces
Get Unique Bounces	*deprecated*
Get Blocks	GET https://api.maileon.com/1.0/reports/get-blocks
Get Unsubscriptions	GET https://api.maileon.com/1.0/reports/unsubscriptions
Get Unsubscription Reasons	GET https://api.maileon.com/1.0/reports/unsubscriptions/reasons
Get Subscribers	GET https://api.maileon.com/1.0/reports/subscribers
Get Recipients	GET https://api.maileon.com/1.0/reports/recipients
Get Filtered Contacts	GET https://api.maileon.com/1.0/reports/filtered_contacts
Get Conversions	GET https://api.maileon.com/1.0/reports/analytics/conversions
Get Unique Conversions	GET https://api.maileon.com/1.0/reports/analytics/conversions/unique
Get Revenue	GET https://api.maileon.com/1.0/reports/analytics/conversions/revenue

Appendices
→ Social Networks List
→ Bouncecodes

Mailings

Resources

Name	Method / URL
Create Mailing	POST https://api.maileon.com/1.0/mailings
Copy Mailing	POST https://api.maileon.com/1.0/mailings/:mailingid/copy
Delete Mailing	DELETE https://api.maileon.com/1.0/mailings/:mailingId
Get Template Mailing	PUT https://api.maileon.com/1.0/mailings/:mailingId/template
Set Template Mailing	PUT https://api.maileon.com/1.0/mailings/:mailingId/template
Reset Contents to Template	PUT https://api.maileon.com/1.0/mailings/:mailingId/contents/reset
Get Mailings By Schedule Time	GET https://api.maileon.com/1.0/mailings/filter/scheduletime
Get Mailings By States	GET https://api.maileon.com/1.0/mailings/filter/states
Get Mailings By Types	GET https://api.maileon.com/1.0/mailings/filter/types
Get Mailings By Subject	GET https://api.maileon.com/1.0/mailings/filter/subject
Get Mailings By Creator_Name	GET https://api.maileon.com/1.0/mailings/filter/creatorname
Get Mailings By Keywords	GET https://api.maileon.com/1.0/mailings/filter/keywords
Get Mailing ID By Name	GET https://api.maileon.com/1.0/mailings/name/:mailingName
Get Name	GET https://api.maileon.com/1.0/mailings/:mailingid/name
Set Name	POST https://api.maileon.com/1.0/mailings/:mailingid/name
Get Type	GET https://api.maileon.com/1.0/mailings/:mailingid/type
Get State	GET https://api.maileon.com/1.0/mailings/:mailingid/state
Is Sealed	GET https://api.maileon.com/1.0/mailings/:mailingid/sealed
Disable QoS Checks	PUT https://api.maileon.com/1.0/mailings/:mailingid/settings/disableQosChecks
Get Tracking Strategy	GET https://api.mailing.com/1.0/mailings/:mailingid/settings/trackingstrategy
Set Tracking Strategy	POST https://api.mailing.com/1.0/mailings/:mailingid/settings/trackingstrategy
Get Max Content Size	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/maxcontentsize
Get Speed Level	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/speedlevel
Set Speed Level	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/speedlevel
Get Tags	GET https://api.mailing.com/1.0/mailings/:mailingid/settings/tags
Set Tags	POST https://api.mailing.com/1.0/mailings/:mailingid/settings/tags
Get Locale	GET https://api.mailing.com/1.0/mailings/:mailingid/settings/locale
Set Locale	GET https://api.maileon.com/1.0/reports/analytics/conversions
Get Subject	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/subject
Set Subject	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/subject
Get Preview Text	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/previewtext
Set Preview Text	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/previewtext
Get Sender Address	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/sender
Set Sender Address	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/sender
Get Sender Alias	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/senderalias
Set Sender Alias	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/senderalias
Get Reply-To-Address	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/replyto
Set Reply-To-Address	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/replyto
Get Recipient Alias	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/recipientalias
Set Recipient Alias	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/recipientalias
Get Html	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/html
Set Html	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/html
Get Text	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/text
Set Text	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/text
Fill RSS SmartContent Tags	POST https://api.maileon.com/1.0/mailings/:mailingid/contents/smartmailing/rss
Send Now	POST https://api.maileon.com/1.0/mailings/:mailingid/sendnow
Add Attachment	POST https://api.maileon.com/1.0/mailings/:mailingid/attachments
Get Attachment	GET https://api.maileon.com/1.0/mailings/:mailingid/attachments/:attachmentid
Get Attachments	GET https://api.maileon.com/1.0/mailings/:mailingid/attachments
Get Count Attachments	GET https://api.maileon.com/1.0/mailings/:mailingid/attachments/count
Delete Attachment	DELETE https://api.maileon.com/1.0/mailings/:mailingid/attachments
Delete Attachments	GET https://api.maileon.com/1.0/mailings/:mailingid/contents/previewtext
Copy Attachments	PUT https://api.maileon.com/1.0/mailings/:targetmailingid/attachments
Get Max Attachment Size	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/maxattachmentsize
Get Mailing Archive URL	GET https://api.maileon.com/1.0/mailings/:mailingid/archiveurl
Get Mailing Report URL	GET https://api.maileon.com/1.0/mailings/:mailingid/reporturl
Sent Testmail to Single Contact	POST https://api.maileon.com/1.0/mailings/:mailingid/sendtestemail
Send Testmail to Test Targetgroup	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/testsendout
Get Test Sendout result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/testsendout
Start Attention check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/attention
Get Attention check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/attention
Start Display check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/display
Get Display check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/display
Start Image check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/image
Get Image check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/image
Start Link check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/link
Get Link check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/link
Start Message Size check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/messagesize
Get Message size check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/messagesize
Start Spam check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/spam
Get Spam check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/spam
Add custom mailing properties	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/properties
Update custom mailing properties	PUT https://api.maileon.com/1.0/mailings/:mailingid/settings/properties
Get custom mailing properties	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/properties
Delete custom mailing properties	DELETE https://api.maileon.com/1.0/mailings/:mailingid/settings/properties
Get mailing blacklists	GET https://api.maileon.com/1.0/mailings/:mailingid/mailingblacklists
Add mailing blacklist	POST https://api.maileon.com/1.0/mailings/:mailingid/mailingblacklists/:blacklistid
Remove mailing blacklist	DELETE https://api.maileon.com/1.0/mailings/:mailingid/mailingblacklists/:blacklistid
Get mailing domain	GET https://api.maileon.com/1.0/mailings/:mailingid/domain
Get Thumbnail	GET https://api.maileon.com/1.0/mailings/:mailingId/contents/thumbnail
Get Thumbnail URL	GET https://api.maileon.com/1.0/mailings/:mailingId/thumbnailurl

Resources only applicable for regular mailings

Name	Method / URL
Get Target Group Id	GET https://api.maileon.com/1.0/mailings/:mailingid/targetgroupid
Set Target Group Id	POST https://api.maileon.com/1.0/mailings/:mailingid/targetgroupid
Create Schedule	PUT https://api.maileon.com/1.0/mailings/:mailingid/schedule
Get Schedule	GET https://api.maileon.com/1.0/mailings/:mailingid/schedule
Update Schedule	POST https://api.maileon.com/1.0/mailings/:mailingid/schedule
Delete Schedule	DELETE https://api.maileon.com/1.0/mailings/:mailingid/schedule
Set Contact Limit	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/contacts_limit
Get Contacts Limit	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/contacts_limit
Set target group update setting	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/targetgroup_update
Check target group update setting	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/targetgroup_update
Start Personalization check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/personalization
Get Personalization check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/personalization
Start Approval sendout	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/approvalprocess
Get Approval Sendout result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/approvalprocess
Start Bounce check	POST https://api.maileon.com/1.0/mailings/:mailingid/checks/bounce
Get Bounce check result	GET https://api.maileon.com/1.0/mailings/:mailingid/checks/bounce
Get „Post-Sendout Cleanup“ State	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/post_sendout_cleanup
Set „Post-Sendout Cleanup“ State	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/post_sendout_cleanup

Resources only applicable for trigger mailings

Name	Method / URL
Create Dispatching	PUT https://api.maileon.com/1.0/mailings/:mailingid/dispatching
Get Dispatching	GET https://api.maileon.com/1.0/mailings/:mailingid/dispatching
Delete Trigger	DELETE https://api.maileon.com/1.0/mailings/:mailingid/dispatching
Get „Ignore Permission“ State	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/ignorepermission
Set „Ignore Permission“ State	POST https://api.maileon.com/1.0/mailings/:mailingid/settings/ignorepermission

Resources only applicable for doi mailings

Name	Method / URL
Get DOI Key	GET https://api.maileon.com/1.0/mailings/:mailingid/settings/doi_key
Set DOI Key	POSThttps://api.maileon.com/1.0/mailings/:mailingid/settings/doi_key

CMS2 specific methods

Name	Method / URL
Get Mailing As Zip	GET https://api.maileon.com/1.0/mailings/:mailingId/cms2/contents
Save Mailing to Template Library	POST https://api.maileon.com/1.0/mailings/:mailingId/cms2/contents
Set Template	PUT https://api.maileon.com/1.0/mailings/:mailingId/cms2/contents
Get Templates	GET https://api.maileon.com/1.0/media/templates/mailings/cms2

Appendices
→ Merge Tags

Transactions (Called Contact-Events in Maileon-UI)

Transactions API Overview
Resources

Name	Method / URL
Get All Transaction Types	GET https://api.maileon.com/1.0/transactions/types
Get All Transaction Types Count	GET https://api.maileon.com/1.0/transactions/types/count
Get Transaction Type	GET https://api.maileon.com/1.0/transactions/types/:transactionTypeId
Create Transaction Type	POST https://api.maileon.com/1.0/transactions/types
UpdateTransaction Type	PUT https://api.maileon.com/1.0/transactions/types
Delete Transaction Type	DELETE https://api.maileon.com/1.0/transactions/types/:transactionTypeId
Create Transactions	POST https://api.maileon.com/1.0/transactions
Delete Transactions Before a Given Date	DELETE https://api.maileon.com/1.0/transactions
Get Transaction	GET https://api.maileon.com/1.0/transactions/:transactionTypeId/transaction_id/:transactionId
Delete Transaction	DELETE https://api.maileon.com/1.0/transactions/:transactionTypeId/transaction_id/:transactionId

Marketing-Automation

Resources

Name	Method / URL
Start MA Program	POST https://api.maileon.com/1.0/marketing-automation/:programId

Media

Resources

Name	Method / URL
Get List of Mailing Templates	GET https://api.maileon.com/1.0/media/templates/mailings

Blacklists

Blacklists Overview
Resources

Name	Method / URL
Get Blacklists	GET https://api.maileon.com/1.0/blacklists
Get Blacklist	GET https://api.maileon.com/1.0/blacklists/:blacklistId
Add Entries to Blacklist	POST https://api.maileon.com/1.0/blacklists/:blacklistId/actions

Mailing Blacklists

Resources

Name	Method / URL
Get Mailing Blacklists	GET https://api.maileon.com/1.0/mailingblacklists
Get Mailing Blacklist	GET https://api.maileon.com/1.0/mailingblacklists/:id
Create Mailing Blacklist	POST https://api.maileon.com/1.0/mailingblacklists
Update Mailing Blacklist	PUT https://api.maileon.com/1.0/mailingblacklists/:id
Delete Mailing Blacklist	DELETE https://api.maileon.com/1.0/mailingblacklists/:id
Add expressions to mailing blacklist	POST https://api.maileon.com/1.0/mailingblacklists/:id/expressions
Get MailingBlacklist Expressions	GET https://api.maileon.com/1.0/mailingblacklists/:blacklistId/expressions