Overview

The REST API allows programmatic access to MessageX services. To use the REST API, you will need an MessageX account and an API key and secret. You can generate those inside your MessageX account. The REST API can be accessed at api.messagex.com. Use of SSL is supported and strongly encouraged. The REST API takes full advantage of all HTTP headers. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

REST and JSON have become the industry standard for APIs so hopefully ours should be easy to learn. Other benefits of REST and JSON is that they are easy to read by human beings and that they can easily be implemented in browsers, from your server and from mobile apps.

API Versioning

Our API will be versioned with "v1", "v2" etc. in the URL path. We will ensure that our API is as much as possible backwards compatible, but if we have to break backwards compatibility, we will increment the API version and make sure that we will continue to support the old version until you are ready to upgrade so we will never break your code. We will make sure that your code works with the API in case of following changes.

  • Adding a new optional parameters or changing the order of parameters of existing resources, both for requests and responses
  • Adding new API resources

Response status codes

Status code Description
200 Everything is okay with your request.
202 We will process your request within certain period of time. Used when operation is time consuming.
400 The request you send is malformed (wrong content type).
402 Your credit balance is insufficient for operation to complete.
403 Something is wrong with authentication
404 Requested resource is not found.
422 Request body could not be processed.
503 Service is unavailable due to infrastructure or network problems.

SDKs

PHP

Official SDK for MessageX API cat be found at GitHub. Its goal is to provide easy integration with all MessageX services in PHP and build robust applications and software with those services. We want this SDK to be community driven and led by us. You can get started in minutes by installing SDK through composer.

Authentication

The REST API uses an HMAC authentication scheme. All requests to resources must be accompanied by a correct Authorization header as per this specification. HMAC Signature authentication is added to our APIs in order to establish necessary security and integrity. Api gateway will validate the digital signature sent in the Authorization header. Authorization: HMAC username="your API key", algorithm="hmac-sha256", headers="Signature Headers", signature="digital signature"

Parameter Description
Username API key obtained from MessageX account.
Algorithm Algorithm used to sign a request. Currently supported are only sha256 and sha512.
Headers Headers that will be used in request signing. The order of headers in this parameter must match to the order of headers in the request.
Signature Digital signature that will be checked by API gateway to validate request.

Email

Send an email Show example

This endpoint allows you to send email over MessageX API. Maximum limit for the number of total recipients is 1000. Name of the receivers or senders can be added using notation with a name (Name <Email Address>). Adding a name is not required, adding just email address is also supported. At the moment only following content types are support for the email body.

  • text/html
  • text/plain
PHP
  • Request
  • Response
require 'vendor/autoload.php';
    
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
  'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
]);

$emailClient->sendEmail(
  (new Email('John Doe ', ['Jane Doe ']))
    ->setSubject('Greetings')
    ->addBody(new Body('text/plain', 'Hi Jane'))
);

                  
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ 
  "from":​ ​"John​ Doe​ <john.doe@example.com>"​,
  ​"to":​ ​[​"Jane​ ​Doe​ ​<jane.doe@example.com>"​],
  "subject":​ ​"Greetings"​, 
  "body":​ ​{ 
    ​"mime":​ ​"text/html"​, 
    "content":​ ​"Hi Jane" 
​  }
}

                  

Add CC and BCC Show example

API also supports adding CC and BCC in the email. Maximum number of each goes into total number of recipients.

PHP
  • Request
  • Response
require 'vendor/autoload.php';
  
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
    'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
]);

$emailClient->sendEmail(
  (new Email('John Doe ', ['Jane Doe ']))
    ->setSubject('Greetings')
    ->addBcc(['John Doe '])
    ->addCc(['John Doe '])
    ->addBody(new Body('text/plain', 'Hi Jane'))
);

                  
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ ​
  "from":​ ​"John​ Doe​ ​<john.doe@example.com>"​, 
  ​"to":​ ​[​"Jane​ ​Doe​ ​<jane.doe@example.com>"​],
  ​"cc":​ ​[​"Alice​ ​Doe​ ​<alice.doe@example.com>"​], 
  ​"bcc":​ ​[​"Bob​ ​Doe​ <bob.doe@example.com>"​], 
  ​"subject":​ ​"Greetings"​,
  ​"body":​ ​{ 
    ​"mime":​ ​"text/html"​, 
    ​"content":​ ​"Hi​ ​Jane" 
​ ​ } 
} 

                

Add Attachment Show example

Add one or more attachments to the email in total size of 25MB.

PHP
  • Request
  • Response
require 'vendor/autoload.php';
    
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\ValueObject\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe ', ['Jane Doe ']))
        ->addAttachment(Attachment::fromFile('path/to/file.pdf'))
        //...
);

                
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ 
  "from":​ ​"John​ Doe​ <john.doe@example.com>"​, ​
  "to":​ ​[​"Jane​ Doe​ <jane.doe@example.com>"​], 
  "subject":​ ​"Greetings"​, 
  "body":​ ​{ 
    "mime":​ ​"text/html"​, 
    "content":​ ​"Hi​ ​Jane" 
  }, 
  "attachments":​ ​[ 
    { 
      "name":​ ​"photo"​, 
      "content":​ "image/jpeg"​, 
      "mime":​ ​"(base64​ ​encoded​ ​file​ ​content)" 
    } 
  ] 
} 

                

Custom Tags Show example

Tags are custom text labels associated with the the email. Maximum number of tags that can be added is 5.

PHP
  • Request
  • Response
require 'vendor/autoload.php';
    
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\ValueObject\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe ', ['Jane Doe ']))
        ->addTag('Tag1')
        //...
);

                
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ 
  "from":​ ​"John​ ​Doe​ ​<john.doe@example.com>"​, 
  "to":​ ​[​"Jane​ ​Doe​ ​<jane.doe@example.com>"​], 
  "subject":​ ​"Greetings"​, 
  "body":​ ​{ 
    "mime":​ ​"text/html"​, 
    "content":​ ​"Hi​ ​Jane" 
  }, 
  "tags":​ ​[​"Tag1"​,​ ​"Tag2"​] 
}

                

Custom Headers Show example

Also custom headers will be added to the email and sent to the recipients. Maximum number of custom headers that can be added is 5.

PHP
  • Request
  • Response
require 'vendor/autoload.php';
    
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\ValueObject\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe ', ['Jane Doe ']))
        ->addHeader('X-Custom-Header', 'Value')
        //... 
);

                
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ 
  "from":​ "John​ Doe​ ​<john.doe@example.com>"​, 
  "to":​ ​[​"Jane​ Doe​ ​<jane.doe@example.com>"​], 
  "subject":​ ​"Greetings"​, 
  "body":​ { 
    "mime":​ ​"text/html"​, 
    "content":​ "Hi​ ​Jane" 
  }, 
  "headers":​ ​[ 
    { 
    "name":​ ​"X-Custom-Header"​, 
    "value":​ ​"Foo" 
    } 
  ]
}

                

Mail Merge Show example

Properties are representing placeholder strings in email body and value for each property is array of replacements for all recipients. Number of replacements for each placeholder must match number of recipients. Order of replacements for each placeholder must match order of recipients.

PHP
  • Request
  • Response
require 'vendor/autoload.php';
    
use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body;
use MessageX\Service\Email\ValueObject\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe ', ['Jane Doe ', 'Alice Doe ']))
        ->addBody(new Body('text/plain', 'Hi {{name}}'))
        ->addSubstitution('name', ['Jane', 'Alice'])
        //...
);

                
  • Response Code: 200
  • Headers: Content-Type: application/json

Body

{ 
  "from":​ ​"John​ ​Doe​ ​<john.doe@example.com>"​, 
  "to":​ ​[​"Jane​ Doe​ ​<jane.doe@example.com>"​,​ ​"Alice​ ​Doe <alice.doe@example.com>"​], 
  "subject":​ ​"Greetings"​, 
  "body":​ ​{ 
    "mime":​ ​"text/html"​, 
    "content":​ ​"Hi​ ​{{name}}" 
  }, 
  "substitutions":​ ​ { 
    "name":​ ​[​"Jane"​, ​"Alice"​] 
  }
}