Add a Subscriber

Learn how to use the Mobile Text Alerts API to add a subscriber to your account

The Mobile Text Alerts API allows you to view, add, edit, and remove subscribers from your account just like you can from the platform dashboard page. This page will guide you through adding a subscriber with the API.

Already have a contact list? You can import contacts in bulk via a spreadsheet or integration instead of adding them individually through the API.

Add a Subscriber with the Mobile Text Alerts API

Subscribers can be added via the API with a POST request to the /subscribers endpoint. A phone number (number) or email address (email) is required. If you add a phone number or email of a subscriber that already exists on the account, this will update the existing subscriber with any changes.

Example request to add a subscriber

Below you can see example POST requests to the /subscribers endpoint to add a new subscriber:

curl --location --request POST 'https://api.mobile-text-alerts.com/v3/subscribers' \
  --header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "firstName": "FirstName",
    "lastName": "LastName",
    "number": 8002223333,
    "email": "[email protected]"
  }'

Requirements: Node.js 18+ (native fetch) and an MTA_API_KEY environment variable.

async function main() {
  const response = await fetch('https://api.mobile-text-alerts.com/v3/subscribers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MTA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      firstName: 'Sarah',
      lastName: 'Johnson',
      number: '+12345678900',
      email: '[email protected]',
      groupIds: [123, 456],
      subscriberFields: {
        '2000': 'January 1st, 2000',
        '2001': 'Premium'
      }
    })
  });

  const data = await response.json();
  console.log(data);
}

main().catch((err) => {
  console.error('Request failed:', err);
  process.exitCode = 1;
});

Requirements: pip install requests and an MTA_API_KEY environment variable.

import requests
import os

response = requests.post(
    'https://api.mobile-text-alerts.com/v3/subscribers',
    headers={
        'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'firstName': 'Sarah',
        'lastName': 'Johnson',
        'number': '+12345678900',
        'email': '[email protected]',
        'groupIds': [123, 456],
        'subscriberFields': {
            '2000': 'January 1st, 2000',
            '2001': 'Premium'
        }
    }
    )
print(response.json())

To view all possible request parameters see: Create Subscriber API Endpoint

Example Response

If valid, a response will be returned with the message: "Subscriber created successfully."

//Example successful response
{
    "message":"Subscriber created successfully.",
    "data":
    {
        "id":109021633,
        "firstName":"FirstName",
        "lastName":"LastName",
        "email":"[email protected]",
        "number":8002223333,
        "e164Number":"+18002223333",
        "date":{"val":"CURRENT_TIMESTAMP"},
        "countryId":209,
        "groups":[],
        "subscriberFieldData":[],
        "signupMethod":5,
        "longNumber":8002223333,
        "carrierId":"41"
    }
}

Create Subscriber

post

Add a new subscriber. If given a phone number or email that already exists tied to the same account, updates the existing subscriber with new information

Required Fields: email or number

Rate Limiting

This endpoint overrides the general rate limit with an account rate limit. Requests are limited by the authenticated account instead of the IP address. This endpoint is limited to 15 requests every 15 seconds

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

SubscriberRequest

firstNamestringRequired

lastNamestringRequired

emailstringRequired

numbernumberRequired

groupIdsnumber[]Required

employeeNumberstringRequired

welcomeMessagestringRequired

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

429

RateLimitError

application/json

500

InternalServerError

application/json

post

/subscribers

POST /v3/subscribers HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "firstName": "text",
  "lastName": "text",
  "email": "text",
  "number": 1,
  "groupIds": [
    1
  ],
  "subscriberFields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "employeeNumber": "text",
  "welcomeMessage": "text"
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "number": 1,
    "e164Number": "text",
    "date": "2026-02-03T23:08:40.800Z",
    "countryId": 1,
    "groups": [
      {
        "id": 1,
        "name": "text",
        "addedToGroupAt": "2026-02-03T23:08:40.800Z"
      }
    ],
    "subscriberFieldData": [
      {
        "id": 1,
        "subscriberFieldId": 1,
        "data": "text"
      }
    ],
    "signupMethod": 1,
    "longNumber": 1,
    "carrierId": 1
  }
}

More Subscriber Actions

PreviousSend a Message NextSetting up Webhooks

Last updated 4 days ago

Was this helpful?

hashtagAdd a Subscriber with the Mobile Text Alerts API

hashtagExample request to add a subscriber

hashtagExample Response

hashtagCreate Subscriber

hashtagRate Limiting

hashtagMore Subscriber Actions

Add a Subscriber with the Mobile Text Alerts API

Example request to add a subscriber

Example Response

Create Subscriber

Rate Limiting

More Subscriber Actions