Send Messages from the API

Before you start

You need an API key. If you don't have one, see Generate and use API keys.

Send a message

curl -X POST https://api.coop.example.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Your appointment is confirmed for tomorrow at 2pm."
  }'

The response includes the message ID and initial status:

{
  "id": "msg_abc123",
  "status": "queued",
  "to": "+15551234567",
  "body": "Your appointment is confirmed for tomorrow at 2pm.",
  "createdAt": "2025-01-15T10:30:00Z"
}

Send with options

You can set priority, choose the sender number, and attach files:

curl -X POST https://api.coop.example.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Here is the document you requested.",
    "priority": 80,
    "fromNumber": "+15559876543",
    "attachments": ["https://files.example.com/document.pdf"]
  }'

priority — 0 to 100. Higher values are processed first.
fromNumber — send from a specific registered phone number.
attachments — array of URLs, up to 10 per message.

Check delivery status

Poll the status endpoint with the message ID:

curl https://api.coop.example.com/api/v1/messages/msg_abc123/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Or set up a webhook to get notified automatically when messages are sent, delivered, or fail.

Handle errors

If the request is malformed, you'll get a 400 with details:

{
  "error": "validation_error",
  "message": "\"to\" must be a valid E.164 phone number or email address",
  "statusCode": 400
}

If your rate limit is exceeded, you'll get a 429 with a Retry-After header.

See the Messages API reference for the complete request/response specification.