Sending Messages

Learn how to send SMS and MMS messages using the Approved Contact API. This guide covers simple text messages, multimedia messages, bulk sends, and advanced messaging patterns.

SMS Messages

SMS (Short Message Service) messages are text-only messages up to 160 characters per segment. Messages longer than 160 characters will be split into multiple segments and automatically concatenated on the recipient's device.

Basic SMS Example

curl -X POST https://api.approvedcontact.com/api/v1/messages \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Your appointment is confirmed for tomorrow at 2 PM."
  }'

import requests
import base64

username = "your-email@example.com"
password = "your-password"
credentials = base64.b64encode(f"{username}:{password}".encode()).decode()

url = "https://api.approvedcontact.com/api/v1/messages"
headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/json"
}

payload = {
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Your appointment is confirmed for tomorrow at 2 PM."
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var username = "your-email@example.com";
var password = "your-password";
var credentials = Convert.ToBase64String(
    Encoding.ASCII.GetBytes($"{username}:{password}"));

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Basic", credentials);

var payload = new
{
    from = "+15551234567",
    to = new[] { "+15559876543" },
    body = "Your appointment is confirmed for tomorrow at 2 PM."
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.approvedcontact.com/api/v1/messages", 
    content);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

const axios = require('axios');

const username = 'your-email@example.com';
const password = 'your-password';
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

const url = 'https://api.approvedcontact.com/api/v1/messages';
const headers = {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
};

const payload = {
    from: '+15551234567',
    to: ['+15559876543'],
    body: 'Your appointment is confirmed for tomorrow at 2 PM.'
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.response.data));

SMS Best Practices

• Character Limits: Keep messages under 160 characters to avoid segmentation
• Encoding: Use GSM-7 character set when possible (avoid emojis in SMS)
• Message Length: If your message is split, you're charged per segment
• Clear CTA: Include a clear call-to-action in your message

MMS Messages

MMS (Multimedia Messaging Service) messages can include images, videos, audio files, and longer text content. First, you need to upload your media using the Media API, then reference the media URL in your message.

Step 1: Upload Media

curl -X POST https://api.approvedcontact.com/api/v1/media \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "00000000-0000-0000-0000-000000000000",
    "fileName": "product-image.jpg",
    "mimeType": "image/jpeg",
    "content": "BASE64_ENCODED_IMAGE_DATA"
  }'

Response:

{
  "url": "https://storage.approvedcontact.com/attachments/abc123/product-image.jpg",
  "fileName": "product-image.jpg",
  "mimeType": "image/jpeg",
  "expiresAt": "2025-01-18T10:30:00Z"
}

Step 2: Send MMS with Media

curl -X POST https://api.approvedcontact.com/api/v1/messages \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Check out our new product!",
    "mediaUrls": [
      "https://storage.approvedcontact.com/attachments/abc123/product-image.jpg"
    ]
  }'

Bulk Messaging

You can send the same message to multiple recipients in a single API call. Each recipient receives their own individual message.

{
  "from": "+15551234567",
  "to": [
    "+15559876543",
    "+15558765432",
    "+15557654321"
  ],
  "body": "Reminder: Store closing early today at 6 PM."
}

Asynchronous Messaging

For high-volume or non-time-critical messages, use async mode. Messages are queued for background processing, and you receive an immediate response.

curl -X POST "https://api.approvedcontact.com/api/v1/messages?isAsync=true" \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Your order has been shipped!"
  }'

Response (immediate):

{
  "messageId": "msg_abc123",
  "status": "queued",
  "queuedAt": "2025-01-11T10:30:00Z"
}

When to Use Async

• Sending to more than 100 recipients
• Marketing campaigns
• Non-urgent notifications
• Batch processing scenarios

Message Status

Messages go through several status stages:

Checking Message Status

To check the status of a sent message, make a GET request to the message endpoint with the message ID:

curl -X GET https://api.approvedcontact.com/api/v1/messages/msg_abc123 \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json"

Error Handling

In case of errors, the API will return an appropriate HTTP status code and a JSON response with details about the error. Common error codes include: