Published — v. 1

AI_REST API_Standard

Owned by Sales operations
Aug 29, 2024
12 min read

MailUp Rest API Standard

When to use the MailUp REST AP IThe MailUp REST API gives you access to a variety of methods to manage email campaigns, subscribe and unsubscribe recipients, and retrieving statistics, bounces, etc. 

A few things to keep in mind:

  • The MailUp REST API uses Oauth2 and requires a token refresh;

  • By properly setting the request header you can set the response format as JSON or XML;

  • Each application is tied to a set of application keys, which are used to authorize the application;

  • Users of the application will be authenticated using their own MailUp account credentials;

  • The application keys used in the sample code shall not be used in a production environment.

MailUp Rest API Standard : Authenticating with OAuth v2

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 using the dedicated section of the web application MailUp.

  • 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 of 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 a 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.

MailUp Rest API Standard : Authenticating with OAuth v2 : Authorization and authentication

The MailUp REST API uses OAuth v2 as the authorization and authentication method for validating access to the API resources.

  • Your application will be authorized to communicate with MailUp using a pair of access keys ("Client ID" and "Client Secret").

  • Users of your application will be authenticated using their regular MailUp user credentials

The following endpoints have to be used:

In case an error occurs during the authorization process, HTTP 400 status code is returned.
HTTP 200 or 302 is returned in case of successful authorization. Error descriptions and formats are stated in the OAuth2 protocol documentation, so please refer to it for further details. 

Depending on how authorization requests are made, responses can be JSON messages, form-encoded data, or query string parameters. The OAuth v2 protocol better defines the response data format, according to the different flows. Being OAuth v2 a framework, several authorization flows are supported; they are named "Grants" and can be listed as follows:

MailUp authorization server supports only "Authorization code grant flow" and "Resource owner password grant" (aka "Password flow")

MailUp Rest API Standard : Authenticating with OAuth v2 : Authorization and authentication : Authorization code grant (recommended) 

Authorization code grant (aka "3-legged") is a little bit more complex than the others, but it is robust and safe. In particular, authentication is done on a MailUp page. For your client application, there is no need of storing user credentials, which may become invalid if you change your password. You simply have to call that page passing both the application keys and the URL of your callback page the authentication tokens are returned to. Once you have the tokens you can go on with them. You can use them whenever you need access to an API resource. You just only have to refresh the access token when it expires. There is no need for any further authorization flow unless you have to connect your application to a different MailUp user.

To Get the access token and the refresh token:
curl "https://services.mailup.com/Authorization/OAuth/LogOn?client_id=MYCLIENTID&response_type=code&redirect_uri=MYCALLBACKURL"  
Examples:

  • MYCALLBACKURL=http://127.0.0.1:8080/rest/index.html

  • MYCLIENTID=0a111fe1-aaaa-bbbb-cccc-f33d3d3efcd3
      
    Note: you have to provide a callback page that accepts POST parameters in this format:
        { "access_token":"MYACCESSTOKEN", "expires_in":3600, "refresh_token":"MYREFRESHTOKEN"}

MailUp Rest API Standard : Authenticating with OAuth v2 : Authorization and authentication : Resource Owner Password Grant 

Using the Resource Owner Password Grant (aka "password flow") you can call a resource and immediately get the tokens in the response. There are some warnings you should care about:

  • password may change, if you save it on your client your application may stop working when a stored password is no more valid

  • if you store the password on your client you are responsible for keeping it safe

To Get the access token and the refresh token:

curl -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&username=MYUSERNAME&password=MYPASSWORD"
 
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"
    }

MailUp Rest API Standard : Authenticating with OAuth v2 : 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. 

 According to the OAuth v2 specification, an access token needs to be provided in the request's HTTP header to access protected information/resources. MailUp API requires using the "Bearer Token". Please check out the example below or refer to the RFC 6750 page for details.

Resource access by specifying access token:
curl -H "Authorization:Bearer MYACCESSTOKEN" /
        -H "Content-Type:application/x-www-form-urlencoded" MYRESOURCEENDPOINT
  
Examples:

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Request format

These are the available resource endpoints:

The structure of the exchanged information is detailed in the automatic web documentation, available by appending "/help" to any endpoint's URL address. 

Any API resource supports some of the following HTTP verbs:

  • GET: used to retrieve a resource;

  • POST: used to create a new resource;

  • PUT: used to modify an existing resource;

  • DELETE: used to eliminate an existing resource;

The message request format (XML or JSON) should be declared by specifying the "Content-Type" header field. 

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Access restrictions

An application can access an account's resources only if it has a valid pair of API keys and a valid access token is provided.

In addition to these main criteria, the resource access may be subject to one or more of the following constraints (others may be added in the future):

  1. Account or user restrictions: when accessing from API impersonating a MailUp user, you will find the same restrictions that you have when you log in to the MailUp web application with the same user. E.g. a maximum number of total mailings for trial accounts, possible restrictions on MailUp lists accessible to a user in case of multi-user accounts...

  2. Frequency of calls (Rate Limiting): a check is performed on the frequency of the calls by the method, enabling only the calls which fall within a defined range of calls per second (the default value is 5 per second, HTTP 403 is returned when this limit is exceeded)

MailUp reserves the right at any time to limit, suspend or ban any user or client application that may be found abusing the API services.

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Response format

The resource endpoints respond to a request by returning data in either JSON or XML format depending on the value of the "Accept" header parameter specified in the request.

Returned data format:

In case of successful access to the requested resource, an HTTP 200 status code is returned, along with the requested data.
Should an error occur (e.g. caused by malformed request, invalid token, frequency call restrictions, or user access privilege limitations), the following error codes are returned:

  • HTTP 400 (Bad request): malformed request or missing parameters. In case of an invalid or malformed authorization token (either refresh token or access token), a proper description message is also returned.

  • HTTP 401 (Unauthorized): expired or revoked token.

  • HTTP 403 (Forbidden): the application is requesting a resource that is not in the scope of the impersonated user. 

  • HTTP 429 (Too many requests): it is returned in case of too many requests per second on a single API resource.

  • HTTP 500 (Internal error): returned in case of any resource server-internal problem.

  • HTTP 503 (Service unavailable): temporary error. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

OAuth v2 error codes and error descriptions are returned either as a detailed part of the raised fault or as a header parameter as stated in the Bearer token documentation.

In case of an expired token, you need to refresh it (HTTP 401). In case of an HTTP 401 error, you need to refresh the authorization token, getting a new one utilizing the refresh token. Please note that also the "refresh token" is renewed with the request and the new value is returned in the response body.  

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Access errors due to “Token expired”

  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":"MYNEWREFRESHTOKEN"}

  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

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Access errors due to "Contract not signed" (HTTP 403)

Access to MailUp resources may fail if the authenticated user has not signed the "Terms of service" yet. When this happens, you simply have to access to MailUp admin console using the same user and accept terms and conditions that are displayed immediately after user login.

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
}

MailUp Rest API Standard : Authenticating with OAuth v2 : Resource access : Access errors due to "Too Many Requests" (HTTP 429)

Access to MailUp resources may fail if the client exceeds the expected rate limit. The returned message shows both the exceeded threshold ("Max") and the number of calls that are received instead ("actual").

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":"429",
    "ErrorDescription":"Authorization error (too_many_requests): The call quota is exhausted. Max: 5 calls/second, actual: 9 calls/second, throttling condition expires in: 291 ms, throttling config: 2.",
    "ErrorName":"TooManyRequests",
    "ErrorStack":null
}

MailUp Rest API Standard : Use Resources API to manage your MailUp Account

Using the MailUp Rest API standards it is possible to manage all your MailUp Account.
It is possible

  • Lists and Groups: create, manage, delete: all resources and methods are explained at this link.

  • Recipients: Import, modify, manage, delete: all resources are explained at this link.

  • Email Messages: Create, modify, delete, sent: all resources are explained at this link.

  • Email statistics: Get the statistics related to the Email message sent: all resources are explained at this link.

  • Text Message SMS: Create, modify, delete, sent, get statistics: all resources are explained at this link.

  • MailUp Account: Get details of the connected MailUp Account at this link.

MailUp Rest API Standard : Paging and filtering

Each method that returns lists and collections of resources can be paginated by adding to the URL the following query string parameters.

  • pageSize: defines the page dimension of the collection;

  • pageNumber: defines which page to start from;

Filtering and sorting are supported in API v1.1 by using the following query string parameters:

  • filterby: define the filtering expression for the requested resource;

  • orderby: define the sorting condition to apply to the request results;

Both parameters must be URL encoded due to the possible presence of reserved characters in the query strings.

Best Practices

  • To avoid timeout problems and improve performance, we recommend using pagination and dividing complex processes into smaller and faster ones. This way, the client application is in charge of rebuilding the large data set that would be retrieved from the smaller sets returned by the MailUp system through pagination.

  • URL encoding of the query string parameters is always recommended, even if in some cases the method calls can work without it.

MailUp Rest API Standard : Paging and filtering : Filtering

Resource filtering is done thanks to a dedicated expression evaluator which is capable of transforming the user-provided filter expression into the appropriate SQL statements to query the server database. 
This transformation is achieved in two steps:

  1. The expression parser evaluates the user filter string identifying operands and operators then it builds a token tree which is passed into the expression builder.

  2. The expression builder scans the token tree and maps operands and operators to the appropriate LINQ statements which are then executed against the database to get the results.

MailUp Rest API Standard : Paging and filtering : Filtering : Property accessors

Usually, resource properties can be accessed through dot notation (ex. message.id) but in some cases, when the property represents a list or an array of sub items (ex. console recipient custom fields) square bracket notation can be used (ex. recipient.Fields['name']).
In case a property is not defined on the requested resource, a suitable error message is returned describing the issue.

MailUp Rest API Standard : Paging and filtering : Filtering : Supported operators

There are two supported operators' types :

  • Mathematical / Logical operators define the relation against two resource properties or between a property and a static value (ex resource.Name == 'David'). Supported mathematical and logical operators are:

    • "!", unary "not": returns true if and only if its operand is false

    • "*", Multiply: computes the product of its operands

    • "/", Divide: divides its first operand by its second operand

    • "%", Modulo: computes the remainder after dividing its first operand by its second

    • "+", Add: for numeric types, + computes the sum of its two operands. When one or both operands are of type string, + concatenates the string representations of the operands

    • "-", Subtract: subtract the second operand from the first

    • "<<", binary LeftShift: shifts its first operand left by the number of bits specified by its second operand

    • ">>", binary RightShift: shifts its first operand right by the number of bits specified by its second operand

    • "<", LessThan: returns true if the first operand is less than the second, false otherwise

    • ">", GreaterThan: returns true if the first operand is greater than the second, false otherwise

    • "<=", LessThanOrEqual: returns true if the first operand is less than or equal to the second, false otherwise

    • ">=", GreaterThanOrEqual: returns true if the first operand is greater than or equal to the second, false otherwise

    • "==", Equal: returns true if the values of its operands are equal, false otherwise

    • "!=", NotEqual: returns false if its operands are equal, true otherwise

    • "&", binary And: computes the logical bitwise AND of its operands

    • "^", binary ExclusiveOr: computes the bitwise exclusive-OR of its operands

    • "|", binary Or: computes the bitwise OR of its operands

    • "&&", AndAlso: performs a logical-AND of its bool operands

    • "||", OrElse: performs a logical-OR of its bool operands

  • TypeRegistry operators define a specific resource property characteristic (ex. resource.Email.Contains('mailup.com')).
    TypeRegistry operators are all the type methods and properties as defined by the C# language code definition. For details on method names please refer to MSDN online documentation.
    Supported type are:

    • "bool", System.Boolean;

    • "byte", System.Byte;

    • "char", System.Char;

    • "int", System.Int32;

    • "decimal", System.Decimal;

    • "double", System.Double;

    • "float", System.Single;

    • "object", System.Object;

    • "string", System.String;

    • "DateTime", System.DateTime;

    • "Convert", System.Convert;

    • "Math", System.Math.

MailUp Rest API Standard : Paging and filtering : Type and cast definition

As far as some value casts and definitions can be done through RegistryType operators, direct casting and particular type definition (ex. a DateTime value) can be inferred directly using a specific syntax definition.
In particular:

  • Datetime values: can be written as #yyyy-mm-dd HH:mm:ssZ# (please note that as for ver.1.0 all date values are assumed to be in UTC timezone)

  • Direct cast: This can be achieved through round brackets by specifying one of the supported types. (ex. (int) double value )

  • Numerical type definition: can be specified by short letter suffix (ex. 1.5F define a single floating-point value, 150000L define an Int64 value). Default numerical values are supposed to be integers (Int32). The supported suffix is:

    • "D": double

    • "F": float

    • "L": long

    • "M": decimal

For examples:

  • Request for subscribed list recipient whose email address contains 'mailup.com' sorted by 'name' descending (custom fields)

    • Method: GET

    • URI: /Console/List/{ID_LIST}/Recipients/Subscribed

    • Filter expression: Email.Contains('mailup.com')

    • Sorting expression: Fields['FirstName'] desc

    • Resulting URI: /Console/List/1/Recipients/Subscribed?filterby="Email.Contains(%27mailup.com%27)"&orderby="Fields%5b%27FirstName%27%5d+desc"

  • Request for subscribed list recipient whose first name is 'Davide' sorted by 'Email' descending

    • Method: GET

    • URI: /Console/List/{ID_LIST}/Recipients/Subscribed

    • Filter expression: Fields['FirstName'] == 'Davide'

    • Sorting expression: Email desc

    • Resulting URI: /Console/List/1/Recipients/Subscribed?filterby="Fields%5b%27FirstName%27%5d+%3d%3d+%27Davide%27"&orderby="Email+desc"

  • Request statistics for message views done by recipients whose email contains mailup ordered by view count descending

    • Method: GET

    • URI: Message/{id_Message}/List/Views

    • Filter expression: Email.Contains('mailup')

    • Sorting expression: Count desc

    • Resulting URI: /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)"&orderby="Count+desc"

  • Request statistics for message views done by recipients whose email contains mailup, between 2013/01/01 and 2013/01/31 ordered by view count descending

    • Method: GET

    • URI: Message/{id_Message}/List/Views

    • Filter expression: Email.Contains('mailup') && [Date >= #2013/01/01# && Date < #2013/01/31#]

    • Sorting expression: Count desc

    • Resulting URI: /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+%5bDate+%3e%3d+%232013%2f01%2f01%23+%26%26+Date+%3c+%232013%2f01%2f31%23%5d"&orderby="Count+desc"

  • Request statistics for message views done by recipients whose email contains mailup, in the last 24 hours ordered by view count descending

    • Method: GET

    • URI: Message/{id_Message}/List/Views

    • Filter expression: Email.Contains('mailup') && Date >= DateTime.Now().AddDays(-1)

    • Sorting expression: Count desc

    • Resulting URI: /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+Date+%3e%3d+DateTime.Now().AddDays(-1)"&orderby="Count+desc"

MailUp Rest API Standard : Sorting

Sorting queries define how results should be ordered. Sorting properties are all first-level properties as defined in resource service contracts and only in particular cases (ex. recipient custom fields) second-level ones can be used.
A sorting query is represented by a string of properties and operands divided by a colon (',') and semicolon (';'). Properties that share the same sorting direction can be listed as comma-separated values (ex. name, surname desc). When a different sorting direction has to be specified, the new property list must be separated by the others with a semicolon (ex. name, surname desc; email asc).
The way the sorting query is written, determine also the priority of sorting execution, so in the case of "name desc; email asc" the results are initially ordered by name descending and then by email ascending.