Getting Started

Getting Started

Top ↑

Requirements for accessing the API

  • A BrandMail Account
  • A valid API Key.
  • A Standards Compliant JSON-RPC library
  • Network access over port 80, or port 443 for SSL.

Please contact your System Administrator if you are unsure as to whether you conform to these requirements.

The API connection string which would typically be used is:

  • If a Virtual Host is setup (which Resellers and some Corporate clients use), "" would be replaced with the Virtual Host URL, eg: ""
  • If the Virtual Host is SSL enabled, then the "https" scheme could be used instead of "http"
  • 3.0 reflects the API version being used. At this point in time 3.0 is the most recently officially released version.

Steps for Getting Started

  1. Get Access to a live Account

    You may need to contact the owner of a live BrandMail account that you are planning on developing for. They can then provide you with a Username and Password to access this account by setting you up with a user account.

    Once this has been completed, you can then login and obtain relevant API key information.

  2. Need to get an account?

    Sign up for a free BrandMail account here. This free account will have full access to the API where you can test and build a live integration

  3. Confirm that your system has the API package and network access over port 80 (port 443 for SSL).

  4. Download a JSON-RPC library.

    The API can use any JSON-RPC library.

    For your convenience, the example code in this document appears in both PHP and JSON-RPC. You may want to browse through some of the many implementations available online for download before selecting one.

  5. Generate an API Key so you can access the API.

    To generate an API Key:

    1. Log in to the system.
      The initial screen is the Dashboard.
    2. Click the Account link in the upper right corner of the screen.
      The screen displays the Account Overview page.
    3. At the bottom of the Left column, click API KEYS.
      The screen displays the Manage API Keys page. If this is the first time you are generating an API Key, the message There are no API Keys to show appears.

      You can create multiple API Keys on the Manage API Keys page and give a different API Key to each API User.
    4. Click
      API Key Button
      The Add an API Key dialogue box pops up.

      Add an API Key Dialogue Box

    5. Enter a name for the API Key.
      The name is for display purposes only. We recommend naming the key after its function, and, if it is being generated for a specific person, including the person's name in the key name.
    6. Click
      Generate API Key Button
      The dialogue box now displays your API Key with the message This is a one time key only. Make sure you save this key in a secure location.

      Dialogue showing generated key

    7. After you copy and save the API Key, close the API Key Dialogue Box.
      The new API Key is now listed on the Manage API Keys page.

      Page with API Key

      When calling API methods, supply the API key as the first parameter.

Next Steps

  1. Review and try out the Common Use Cases. If the use cases would add functionality to your system, adapt them so you can use them regularly.

  2. Review the Basic Structure of the API

  3. Learn about Optimising API Performance

  4. Continue to the Method Reference Guide

See Also