Magnews REST API – Getting Started

The magnews REST API allows you to integrate magnews with your systems (CRM, eCommerce, websites, data platforms) and automate activities such as contact management, campaigns, content, and webhooks.

This page provides a general overview and the core concepts you need to get started with the APIs.

If you’re looking for the complete technical details of endpoints, parameters, and payloads, refer to the Reference Guide.

If you’d like to start testing right away, you can use the official Postman collection: it includes ready-to-use requests, examples, and a resource-based structure (contacts, communications, insights, etc.).

What you can do with the REST API

The magnews REST API is organized into functional areas.

Contacts

Complete management of the contact database:

• create, update, merge, or delete contacts;
• manage subscription statuses (subscribe / unsubscribe / suspend);
• query contacts using MQL;
• add or remove contacts from static audiences;
• enroll contacts into workflows;
• perform bulk operations (batch merge, batch delete).

Audiences

Management of audiences used as targets for campaigns and automations:

• retrieve existing audiences;
• create and delete static audiences;
• query audiences using filters;
• use audiences as targets for communications and deliveries.

Communications & Deliveries

Area dedicated to marketing communications (newsletters) and their deliveries:

• retrieve and update newsletter and template information;
• start a delivery;
• manage scheduling (immediate, scheduled, periodic, in multiple stages);
• monitor delivery status;
• pause, resume, or stop a delivery.

Transactional (Simple Messages)

Sending transactional messages (called Simple Messages in the API):

• send single emails and SMS messages;
• send batches of transactional messages;
• send raw MIME messages;
• check message status using internal or external IDs.

Webhooks

Event-driven integration via push notifications:

• create and configure webhooks;
• activate, suspend, or delete subscriptions;
• view webhook history and status.

Insights

Analysis of performance for campaigns, transactional messages, and workflows:

• communication and delivery statistics: opens, clicks, conversions, etc.;
• aggregated or filtered reports by audience, delivery, or query;
• insights on transactional messages;
• insights on workflows.

Data tables

Management of data tables and contact extensions (entities), as well as application data:

• create, update, and query custom entity records;
• use MQL for advanced queries on system and custom data.

Exports and asynchronous operations

• run scheduled tasks (scheduled work);
• export system data and custom data tables using MQL queries.

Account

Service and context endpoints:

• retrieve user and account information;
• check remaining credits by channel (email, SMS).

Base URL and API “version”

All requests start from a base URL such as:

https://ws-mn1.mag-news.it/ws/rest/api

Authentication

Every request must be authenticated. The recommended method is OAuth 2.0, using an access token in the Authorization header:

Authorization: Bearer <access_token>

In some integrations, alternative methods may also be supported (for example, Basic Authentication or tokens in the query string), but for security reasons it is strongly recommended to use Bearer tokens.

OAuth 2.0: quick setup

1) Create a digital certificate

To generate OAuth tokens, you need to create application credentials:

1. In magnews, go to Settings > Web service > Digital certificates
2. Create a new certificate of type Client Application (OAuth 2.0).
3. Store the Client ID and Key Secret securely: you’ll need them to obtain tokens.

If you are testing the interactive flow directly in Postman, set the Redirect URI to:

https://oauth.pstmn.io/v1/browser-callback

If you are integrating your own application, use your app’s redirect URI. If you generate tokens manually from magnews, you can leave it empty.

2) Generate an access token

You have two options:

• Interactive mode: use the requests available in Token management in the Postman collection (Authorization Code Flow) and follow the instructions in the overview.
• Manual mode: in the platform, go to Settings > Web service > Token management, select the certificate and user, then create the token and copy the access token (and, if available, the refresh token).

3) Set variables in Postman

In the collection (or environment) variables, fill in:

4) You’re ready

You can now start exploring the collection folders and testing requests on the main resources (contacts, campaigns, insights, and so on).

Token refresh

If the token expires, you can regenerate it:

• in Postman, using the Refresh token request in the Token management folder;
• programmatically, by implementing a refresh call in your system (see the example in the collection).

Rate limits

To keep the service stable, the APIs apply rate limits configured per customer. If you exceed the allowed threshold within the time window, you will receive:

429 Too Many Requests

Best practice: when you receive a 429 response, implement a retry with backoff mechanism (progressive delays) to avoid further limit violations.

Status codes and errors

Responses use standard HTTP status codes, including:

• 200 OK: request completed successfully.
• 400 Bad Request: missing/invalid parameters or malformed payload.
• 401 Unauthorized: missing or invalid authentication, or expired token.
• 403 Forbidden: insufficient permissions or security restrictions (e.g. WAN Forbidden).
• 404 Not Found: resource not found.
• 429 Too Many Requests: rate limit exceeded.
• 500 Internal Server Error: unexpected server-side error.

Error details (MNError)

In some cases, in addition to the HTTP status code, the response includes a detail object to help you understand what needs to be fixed. You may find fields such as:

• errorType: error category (e.g. EmptyValue, ValueNotValid, UniqueConstraintViolation).
• fieldRef: reference to the field that caused the error.
• debugExplanation: textual explanation to help with debugging.

Recommended next steps

1. Import (or fork) the Postman collection and configure the variables.
2. Verify authentication with a simple request (e.g. reading a test resource).
3. Move on to the key resources for your integration (such as contacts and insights).
4. When going to production, add handling for refresh tokens, errors (400/401/429), and logging.

Postman collection

To make API exploration and testing easier, magnews provides an official Postman collection that includes:

• ready-to-use requests for the main REST endpoints;
• OAuth 2.0 token management;
• a structure organized by resource (contacts, campaigns, insights, webhooks, etc.).

You can fork the collection into your Postman workspace and keep it up to date with periodic pulls, so you always have access to the latest features and endpoints without having to recreate requests from scratch.

GitHub

magnews is also present on GitHub with a set of open-source projects designed for developers and integrators.

If you enjoy exploring and experimenting:

• take a look at the available repositories;
• leave a ⭐ if you find something useful;
• fork or contribute with improvements and new ideas.

It’s the best way to stay up to date with the magnews ecosystem and actively participate in the development of integrations.