Overview

The Mailship API allows users to interact programmatically with the Mailship platform. With this API, you can automate your shipping processes, manage your shipments, and access real-time data, all from within your own applications.

Authentication

To use the Mailship API, you first need to obtain your login credentials (username and password) from our Onboarding department. You can then use these credentials to authenticate with the API and obtain a bearer token.

You can check API reference here.

Here's how to authenticate:

Send a POST request to https://app.mailship.eu/api/login/user
Include the following JSON payload in your request:

{
  "login": "your_username",
  "password": "your_password"
}

Replace "your_username" and "your_password" with your actual login credentials.

The API will respond with a bearer token. You'll need to include this token in the `Authorization` header of your subsequent API requests.

Here's an example of what the `Authorization` header might look like:

Authorization: Bearer your_token

Replace "your_token" with the actual token you received from the API.

Token Usage

The token you receive from the login endpoint includes an expiration time, represented as a Unix timestamp in the exp field. This is the time when the token will expire.

Unix timestamps are a way to track time as a running total of seconds. This count starts at the Unix Epoch on January 1st, 1970 at UTC. Therefore, the Unix timestamp is a way to track time as an absolute quantity. To convert a Unix timestamp to a human-readable format, there are many online tools available.

Here's an example of a response from the login endpoint:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjEyMzQ1Njc4LWFiY2QtMTIzNC1hYmNkLTEyMzx0NTY3ODlhYiIsInR5cGUiOiJhZG1pbiIsImV4cGlyZSI6MTU5MzgyODIyMn0.PlscuLItHb4oRvHBiLO5k1o-O1YzdExp0nlcmmZvQ3k",
  "exp": 1590922425
}

Token Refresh

You can check API reference here.

Before the token expires, you should refresh it by sending a POST request to http://app.mailship.eu/api/refresh-token.

Include the following JSON payload in your request:

{
  "refreshToken": "your_refresh_token"
}

Replace "your_refresh_token" with the actual refresh token you received from the login endpoint.

The refresh-token endpoint will respond with a new token and expiration time.

Quick Tips

Remember to replace 'your_username' and 'your_password' with your actual login credentials.

Please note that these are simplified examples and may not include all necessary error handling or security measures for a production environment. Always make sure to handle potential errors and secure your credentials appropriately.

PHP

Here's a simple example of how you might handle authentication and token refresh in PHP:

<?php
$url = 'https://app.mailship.eu/api/login/user';
$data = array('login' => 'your_username', 'password' => 'your_password');

$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data),
    ),
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }

$token = json_decode($result)->token;

// Use the token in your API requests
// ...

// Refresh the token
$url = 'http://app.mailship.eu/api/refresh-token';
$data = array('refreshToken' => $token);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data),
    ),
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }

$newToken = json_decode($result)->token;
?>

Node.js

Here's a simple example of how you might handle authentication and token refresh in Node.js using the axios library:



const axios = require('axios');

async function authenticate() {
  try {
    const response = await axios.post('https://app.mailship.eu/api/login/user', {
      login: 'your_username',
      password: 'your_password'
    });

    const token = response.data.token;

    // Use the token in your API requests
    // ...

    // Refresh the token
    const refreshResponse = await axios.post('http://app.mailship.eu/api/refresh-token', {
      refreshToken: token
    });

    const newToken = refreshResponse.data.token;

  } catch (error) {
    console.error(error);
  }
}

authenticate();

Authentication + token handling