Get Started with the TextMagic REST API

To start sending text messages using the TextMagic REST API, just follow these steps:

1. Generate the API credentials
2. Connect to our API endpoint

This page provides all the information you need to get started. Here, we explain the following steps:

How to obtain the API credentials

To start sending text messages, you need to create an API key. API keys are similar to an account password; the difference is that an API key only provides access to the API: you cannot log in to TextMagic Online using the API key.

Your program sends the login credentials with each API request as HTTP headers: X-TM-Username is your TextMagic username, while X-TM-Key is your API key.

How to obtain an API key:

  1. Log in to TextMagic (or start a free trial if you haven’t registered yet).
  2. Go to the API settings page.
  3. Click the Add new API key button.
  4. Enter an app name for this key. Note, it’s just a label, so pick any name.
  5. Click Generate new key.
  6. You should now see your new API key in the green notification banner above the table:

Note for API v1 users

V1 keys are not compatible with the V2 version of the TextMagic REST API, so you will need to generate a new API key to use the V2 endpoint.

The API endpoint

The TextMagic REST API endpoint is:

https://rest.textmagic.com/api/v2

All the URLs referenced in this documentation should use this base URL.

How the REST API works

REST APIs use the HTTP protocol to send and receive messages. REST messages are usually encoded as JSON documents and are an improvement over older methods such as the XML based SOAP protocol. REST APIs use the same set of methods that web browsers use: POST, GET, PUT or DELETE. These correspond to the CRUD operations: create, read, update and delete. Often, REST URIs provide direct CRUD access to entities or collections of entities, for example: http://api.foo.com/people. In this instance, to delete a person’s endpoint, you might simply call the endpoint DELETE http://api.foo.com/people/{id}. REST makes these types of operations simple.

Example
Let’s take the entity most often used in messaging: contacts. Imagine you want to perform operations on your contacts list: well, it’s only a matter of calling the following endpoints:
  • GET /api/v2/contacts (get all of your contacts)
  • GET /api/v2/contacts/{id} (get a specific contact)
  • POST /api/v2/contacts (create a new contact)
  • PUT /api/v2/contacts/{id} (update an existing contact)
  • DELETE /api/v2/contacts/{id} (delete an existing contact)

It’s that simple! In fact, that’s all you need to do to manage the contacts in your TextMagic account!

The next step

Congratulations! You’re now ready for TextMagic’s Sandbox, which you can try out (by request) before writing the code. You’ll find the complete documentation for all the functions on the left-hand side of the page. We suggest you start with Messages: Send.