Page Comparison

...

Before you start

MailUp REST API follows OAuth 2.0 specification and authorizes only the applications that specify a pair of valid access keys ("Client ID" and "Client Secret") in the authentication process. 

...

To get your access keys, you must register your application by following the procedure that is described here. 

Basic concepts

Make sure you clearly understand the role of access keys, developer accounts and MailUp user credentials. These notes should be useful:

• API access keys identify a software application (e.g. a plugin for Salesforce that uses MailUp REST API).
  • Access keys are used according to the roles of "client ID" and "client secret" in OAUTH 2.0 specifications.
  • You can use them with any MailUp account, regardless the account they were created from.
  • By requesting a pair of keys, you register your application. So you have to provide details about it and its author.
• A developer account is a free platform that could be requested to MailUp in case your regular account does not let you generate the API access keys.
  • A developer account cannot be converted into a production account and you cannot purchase a subscription plan for it. Use it just for the purposes stated above. 
• User credentials are the username and the password that identify an user of a specific MailUp account
  • When you start using an application, you are asked to provide the credentials of the MailUp account your application has to be connected to. Only at this moment you are linking a pair of access keys to a MailUp user
  • Since the allowed relationships between access keys and MailUp users are "many-to-many", you can use the same access keys with several MailUp accounts.

Let's get started

Once you get the access keys and you have in mind the basic concepts stated above, you are ready to start developing your application. Authentication with OAuth 2.0 is not a walk in the park, the recommended approach is to check out a piece of working code form Samples and Wrappers.

Anyway, if you are not familiar with any of the programming language of our samples, or if you want to know more, you can have a look at the section below.

...

Technical reference

Authorization and authentication

...

• Authorization code grant;
• Implicit grant;
• Resource owner password grant;
• Client credentials grant.

MailUp authorization server can support all of these OAuth v2 grant flows, however we recommend using the "Authorization code grant flow". In a few very special scenarios, e.g. in case of trusted internal application, other flows can be implemented. supports only "Authorization code grant flow" and "Resource owner password grant" (aka "Password flow")

Authorization code grant (recommended) 

...

curl "https://services.mailup.com/Authorization/OAuth/LogOn?client_id=MYCLIENTID&client_secret=MYCLIENTSECRET&response_type=code&redirect_uri=MYCALLBACKURL"
 
Examples:
- MYCALLBACKURL=http://127.0.0.1:8080/rest/index.html
- MYCLIENTID=0a111fe1-aaaa-bbbb-cccc-f33d3d3efcd3
- MYCLIENTSECRET=f00b000e-aaaa-bbbb-cccc-8f2a92111dde
 

 
Note: you have to provide a callback page that accepts POST parameters in this format:
	{ "access_token":"MYACCESSTOKEN", "expires_in":3600, "refresh_token":"MYREFRESHTOKEN"}

...

• password may change, if you save it on your client your application may stop working when stored password is no more valid
• if you store the password on your client you are responsible of for keeping it safe

curl -X POST-X POST https://services.mailup.com/Authorization/OAuth/Token / 
-H "Authorization: Basic BASE64_ENCODED_CLIENTCREDENTIALS" /
-H "Content-Type: application/x-www-form-urlencoded" /
-d "grant_type=password&client_id=MYCLIENTID&client_secret=MYCLIENTSECRET&username=MYUSERNAME&password=MYPASSWORD" /
		https://services.mailup.com/Authorization/OAuth/Token


Examples:
- MYUSERNAME=m1234
- MYCLIENTID=0a111fe1-aaaa-bbbb-cccc-f33d3d3efcd3
- MYCLIENTSECRET=f00b000e-aaaa-bbbb-cccc-8f2a92111dde
- BASE64_ENCODED_CLIENTCREDENTIALS=BASE64(MYCLIENTID:MYCLIENTSECRET)

Response:
{	
	"access_token":"MYACCESSTOKEN",
	"expires_in":3600,
	"refresh_token":"MYREFRESHTOKEN"
}

...

Resource access

After passing the authorization process, the client application impersonates a MailUp user. Then, the resources the user is enabled to get or set are accessible by calling related API endpoints. For more detailed information about available resources and related API methods, please refer to the specific documentation of the REST API Resources. 

...

// #1 When resource access fails because token is expired
curl -H "Authorization:Bearer MYACCESSTOKEN" /
		-H "Content-Type:application/x-www-form-urlencoded" MYRESOURCEENDPOINT 
Response:{"ErrorCode":"401","ErrorDescription":"Authorization error: Access token is expired","ErrorName":"Unauthorized","ErrorStack":null}
 
// #2 First you need to get a new token
curl -X POST -d "client_id=MYCLIENTID&client_secret=MYCLIENTSECRET&refresh_token=MYREFRESHTOKEN&grant_type=refresh_token" /
		https://services.mailup.com/Authorization/OAuth/Token
Response:{	"access_token":"MYNEWACCESSTOKEN","expires_in":3600,"refresh_token":"MYREFRESHTOKEN"}

 
// #3 Then you can successfully access to the resource by using the new token
curl -H "Authorization:Bearer MYNEWACCESSTOKEN" /
		-H "Content-Type:application/x-www-form-urlencoded" MYRESOURCEENDPOINT 

Access errors due to "Contract not signed" (HTTP 403)

...

curl -H "Authorization:Bearer MYACCESSTOKEN" /
		-H "Content-Type:application/x-www-form-urlencoded" /
		https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/1/Groups

Response:
{	
	"ErrorCode":"403",
	"ErrorDescription":"Authorization error: Contract not signed, please login in console and accept terms of service.",
	"ErrorName":"Forbidden",
	"ErrorStack":null
}

...

Access errors due to "Too Many Requests" (HTTP 429)

...