Getting Started

Welcome to the Message2Give API Documentation

The Message2Give API has a wide-range of functionalities that enable you to efficiently communicate with a large audience through many communication mediums, automatically, all at once.

Getting Started

There are a few things you need to know before getting started with Message2Give's APIs.

• Most requests you make will require authentication. See the Authentication page for more info.

• The base URL for each endpoint is https://api.app.message2give.com/2019-01-23

• A request will fail if it does not have all required information.

• GET requests will require you to specify some paramaters in the URL. Parameters will be enclosed in curly braces: {example}.

  • Path paramaters are a part of the endpoint URL. They are always required.

  • Query paramaters are appended to the end of the endpoint URL to specify the nature of the request. They always follow a question mark (?). Some are required. A required query parameter will be indicated with an asterisk (*).

  • For api.url/{target_id}/message?limit={limit} -> target_id is a path parameter, and limit is a query parameter.

  • The purpose of each parameter will be explained in each request.

  • The {workspace_id} parameter can be replaced with self. The request will identify your workspace automatically using the authentication details of the request.

• POST requests will require you to specify the body content of your request.

  • The body is comprised of various properties that modify the functionality of the request.

  • Some properties are required in a request. These required properties will be indicated by an asterisk (*).

  • The functionality of each property will be explained in each request.

  • When using a request body, you will need to include content-type: application/json in the header of the request. This tells the program to interpret your body as JSON.

• The API is directly linked with the Portal. Any modifications made in your workspace using the API (create a campaign, create a template etc.) will appear in the UI for your workspace as well.

• "workspace" and "organisation" are interchangeable terms.

Contact Destinations

To send messages to or from phone numbers and emails using the API, they need to follow rules and formatting.

Number Formatting

All phone numbers must be in E164 format. For example, you might have 61400000000 for an Australian number and 6412345678 for a New Zealand number.

Sending From a Number

To send a message from a certain number using the API, you need to use a Virtual Number or Sender ID. A Virtual Number has to be rented out for your workspace. A Sender ID can be any number or alpha code (alphanumeric string), but it must be approved in your workspace before you can use it.

To send messages to international numbers, you need to contact our support team to confirm the Sender ID requirements for your intended destination. For example, to contact a New Zealand number, you'll need to apply for a short code.

Sending From an Email

To send a message from an email address using the API, it first needs to be added to your workspace as an Email Alias. This Email Alias must also belong to a Domain that has been verified in your workspace.

Global Response Code Guidelines

The Message2Give API responds with standard HTTP response codes according to the status of the response.