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.

It is recommended to submit the number field as type string in E.164 format .

See Phone Number Format Guide to learn more.

Example request to add a subscriber

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

cURL

curl --location --request POST 'https://api.mobile-text-alerts.com/v3/subscribers' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "firstName": "FirstName",
    "lastName": "LastName",
    "number": "[phone]",
    "email": "[e-mail]"
  }'

Node.js

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: '[phone]',
      email: '[e-mail]',
      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;
});

Python

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': '[phone]',
        'email': '[e-mail]',
        '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":"[e-mail]",
        "number":8002223333,
        "e164Number":"[phone]",
        "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

firstNamestringOptional

lastNamestringOptional

emailstringOptional

numberone ofOptional

numberOptional

or

stringOptional

e164NumberstringOptional

groupIdsnumber[]Optional

employeeNumberstringOptional

welcomeMessagestringOptional

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: 201

{
  "firstName": "text",
  "lastName": "text",
  "email": "text",
  "number": 1,
  "e164Number": "text",
  "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-01-01T00:00:00.000Z",
    "countryId": 1,
    "groups": [
      {
        "id": 1,
        "name": "text",
        "addedToGroupAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "subscriberFieldData": [
      {
        "id": 1,
        "subscriberFieldId": 1,
        "data": "text"
      }
    ],
    "signupMethod": 1,
    "longNumber": 1,
    "carrierId": 1
  }
}

More Subscriber Actions

• All Subscribers API endpoints

• Assign Custom Subscriber Attributes

• Group Subscribers