Monolynx Piotr Krych is the controller of your data. We use cookies to run the service, provide helper features, measure visits, and show personalized marketing content. You can accept all categories, reject them, or customize your choice, and change or withdraw consent at any time. See our privacy policy for details.
Recipients by name: Google (analytics, Google Analytics) and Meta and LinkedIn (marketing).
REST API for SMS messaging, contacts and contact groups management. Integrate with N8n, Bitrix24, custom scripts, or any HTTP client.
This API lets you send SMS messages and manage contacts and contact groups programmatically. All 7 public endpoints accept JSON request bodies and return JSON responses. No OAuth or session cookies required — authentication is key-based (see Authentication).
Common use cases: bulk imports from CRM systems, N8n automation workflows, Bitrix24 integration, mass SMS campaigns, and AI agent pipelines.
The API is available under both brand domains. The endpoints and contracts are identical — only the base URL differs.
| Brand | Base URL |
|---|---|
| AwesomeSMS | https://awesomesms.com |
| LepszeSMSy.pl | https://lepszesmsy.pl |
There are two authentication methods depending on the endpoint group. Both use fields included in the JSON request body — no HTTP headers required.
Used by POST /api/messages/ and POST /api/messages/bulk/. Include the field license__key in the request body. The key is 6 or 12 characters long. The license must be active and assigned to a user with a valid subscription.
Used by all /api/contacts/ endpoints. Include both key (6–12 chars, license key) and api_key (exactly 12 chars) in the request body. Both must be valid and belong to the same active account.
| Endpoint | Max per request | Additional limits |
|---|---|---|
| POST /api/messages/bulk/ | 1 000 messages | Daily SMS limit (max_daily_sms) per user |
| POST /api/contacts/contacts/bulk/ | 500 contacts | — |
| POST /api/contacts/groups/bulk/ | 200 groups | — |
When the daily SMS limit is exceeded the request returns 403 Forbidden. Single-item endpoints have no per-request batch limit.
Message text can include the {name} variable. It is replaced with the contact's name by MessagePersonalizationService before the SMS is queued.
{name} — contact name (available in all contact and group endpoints)
Note: the POST /api/messages/ and bulk SMS endpoints operate without a contact context, so {name} personalization is not available there.
SMS Endpoints
Creates a single SMS message. The message is queued and delivered asynchronously by the mobile app (up to 15 min delay depending on the device schedule).
license__key in request body.
| Field | Type | Required | Description |
|---|---|---|---|
| external_id | string | required | Unique message identifier per license. Used for deduplication.max 255 chars |
| license__key | string | required | License key for authentication.6 or 12 chars |
| message | string | required | SMS text content. |
| phone | string | required | Recipient phone number in E.164 format.e.g. +48123456789 |
| send_after | ISO datetime | optional | Earliest time to send the message. If omitted, sending hours policy applies. |
| send_before | ISO datetime | optional | Deadline — message is skipped if not sent before this time. |
| priority | integer | optional | Higher value = higher priority. Default: 10.default: 10 |
{
"external_id": "order-confirmation-12345",
"license__key": "ABC123",
"message": "Your order #12345 has been confirmed. Delivery: 2-3 business days.",
"phone": "+48123456789",
"send_after": "2026-04-10T09:00:00",
"priority": 10
}{
"id": 98765,
"external_id": "order-confirmation-12345",
"phone": "+48123456789",
"message": "Your order #12345 has been confirmed. Delivery: 2-3 business days.",
"status": "pending",
"send_after": "2026-04-10T09:00:00",
"created_at": "2026-04-09T14:32:00Z"
}| Code | Status | Description |
|---|---|---|
| 201 | Created | Message queued successfully. |
| 400 | Bad Request | Missing required fields or validation error. |
| 404 | Not Found | License key not found. |
| 500 | Server Error | Internal server error. |
Creates up to 1 000 SMS messages in a single request. Supports partial success (default) or atomic all-or-nothing mode.
license__key in request body. License must be active (IsLicenseActive) and key must have valid length (LicenseKeyLength).
| Field | Type | Required | Description |
|---|---|---|---|
| license__key | string | required | License key for authentication.6 or 12 chars |
| messages | array | required | Array of SMS objects to send.1–1000 items |
| all_or_nothing | boolean | optional | If true, any validation error aborts the entire batch with rollback. Default: false (partial success).default: false |
| Field | Type | Required | Description |
|---|---|---|---|
| external_id | string | required | Unique identifier per license. Duplicate IDs are skipped.max 255 chars |
| message | string | required | SMS text content. |
| phone | string | required | Recipient phone in E.164 format.+[country][number] |
| send_after | ISO datetime | optional | Earliest send time. If absent, sending hours policy applies. |
| send_before | ISO datetime | optional | Send deadline. |
| priority | integer | optional | Message priority. Higher = sent sooner.default: 10 |
| Reason | Description |
|---|---|
| duplicate_external_id | A message with this external_id already exists for this license. |
| opted_out | The recipient has opted out of SMS messages. |
| outside_sending_hours | send_after was omitted and current time is outside configured sending hours. |
{
"license__key": "ABC123",
"all_or_nothing": false,
"messages": [
{
"external_id": "promo-april-001",
"message": "Spring sale — 20% off all orders this week!",
"phone": "+48123456789",
"priority": 5
},
{
"external_id": "promo-april-002",
"message": "Spring sale — 20% off all orders this week!",
"phone": "+48987654321",
"send_after": "2026-04-10T10:00:00",
"priority": 5
}
]
}{
"created_count": 1,
"skipped_count": 1,
"skipped": [
{
"index": 0,
"reason": "duplicate_external_id",
"external_id": "promo-april-001"
}
]
}| Code | Status | Description |
|---|---|---|
| 201 | Created | Batch processed. Check created_count and skipped array. |
| 400 | Bad Request | Validation error, batch exceeds 1000, or all_or_nothing=true failure. |
| 403 | Forbidden | Inactive license or daily SMS limit exceeded. |
| 404 | Not Found | License key not found. |
Returns a paginated list of SMS messages for the authenticated account. Supports filtering by license key, campaign, phone number and message type. Results are scoped by the 3-tier permission model: regular users see only their own messages, business users see their entire company, superusers see all.
key + api_key as query string parameters (not in body).
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | required | License key.6–12 chars |
| api_key | string | required | API key.12 chars |
| license__key | string | optional | Filter results by license key. |
| campaign__name | string | optional | Filter by campaign name (exact match). |
| phone | string | optional | Filter by recipient phone number. |
| type | string | optional | Filter by message type.SENT | RECEIVED |
| ordering | string | optional | Sort field. Prefix with - for descending. Default: -send_at.e.g. -send_at, phone, priority |
| page | integer | optional | Page number.default: 1 |
| page_size | integer | optional | Results per page.default: 50, max: 1000 |
id, external_id, send_at, message, phone, send_after, send_before, priority, type, created_at, modified_at
GET /api/messages-list/?key=ABC123&api_key=DEF456GHI789&type=SENT&ordering=-send_at&page_size=10{
"count": 142,
"next": "https://awesomesms.com/api/messages-list/?page=2&key=ABC123&api_key=DEF456GHI789",
"previous": null,
"results": [
{
"id": 98765,
"external_id": "order-confirmation-12345",
"campaign": "April Campaign",
"send_at": "2026-04-10T09:00:01Z",
"license": "ABC123",
"message": "Your order #12345 has been confirmed.",
"phone": "+48123456789",
"user": "jan.kowalski",
"send_after": "2026-04-10T09:00:00Z",
"send_before": null,
"priority": 10,
"type": "SENT",
"created_at": "2026-04-09T14:32:00Z",
"modified_at": "2026-04-10T09:00:05Z"
}
]
}| Code | Status | Description |
|---|---|---|
| 200 | OK | Paginated list returned. Empty results array when no messages match. |
| 401 | Unauthorized | Missing, invalid, or inactive key / api_key. |
Contact Endpoints
Creates a new contact or updates an existing one (matched by phone number per user). Optionally assigns to a group and sends an SMS — all in a single request.
key + api_key in request body.
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | required | License key.6–12 chars |
| api_key | string | required | API key.12 chars |
| name | string | required | Contact full name. |
| phone | string | required | Phone in E.164 format.+[country][number] |
| group_name | string | optional | Group to assign the contact to. Created automatically if it does not exist. |
| message | string | optional | SMS content. Supports {name} personalization. Requires send_after. |
| send_after | ISO datetime | optional | Required when message is provided. Earliest time to send the SMS. |
| send_before | ISO datetime | optional | SMS send deadline. |
| priority | integer | optional | SMS priority. Default: 10.default: 10 |
| ignore_foreign_numbers | boolean | optional | Skip SMS sending for non-local phone numbers. Default: false.default: false |
Phone already exists (same user) → contact name is updated, returns 200 OK
New phone → contact is created, returns 201 Created
group_name → group created via get_or_create (case-sensitive)
{
"key": "ABC123",
"api_key": "DEF456GHI789",
"name": "Jan Kowalski",
"phone": "+48123456789",
"group_name": "VIP Clients",
"message": "Welcome {name}! You have been added to our VIP list.",
"send_after": "2026-04-10T09:00:00",
"priority": 10,
"ignore_foreign_numbers": false
}{
"id": 5432,
"name": "Jan Kowalski",
"phone": "+48123456789",
"group_name": "VIP Clients",
"created": true
}| Code | Status | Description |
|---|---|---|
| 200 | OK | Contact updated (phone already existed). |
| 201 | Created | New contact created. |
| 400 | Bad Request | Missing fields, invalid phone format, or send_after missing when message is provided. |
| 401 | Unauthorized | Invalid or inactive license / API key. |
Creates or updates up to 500 contacts in a single request. Optimised with bulk DB operations: one pre-fetch query for existing contacts, one for existing groups, and bulk_create / bulk_update for new objects.
key + api_key in request body.
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | required | License key.6–12 chars |
| api_key | string | required | API key.12 chars |
| contacts | array | required | Array of contact objects.1–500 items |
| ignore_foreign_numbers | boolean | optional | Skip SMS for non-local numbers. Applied globally to all items.default: false |
| all_or_nothing | boolean | optional | Reserved for future use.default: false |
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | required | Contact full name. |
| phone | string | required | E.164 format.^\+[1-9]\d{1,14}$ |
| group_name | string | optional | Group to assign. Created if not exists. |
| message | string | optional | SMS content. Supports {name} personalization. |
| send_after | ISO datetime | optional | Required when message is provided. |
| send_before | ISO datetime | optional | SMS send deadline. |
| priority | integer | optional | SMS priority.default: 10 |
{
"key": "ABC123",
"api_key": "DEF456GHI789",
"ignore_foreign_numbers": false,
"all_or_nothing": false,
"contacts": [
{
"name": "Anna Nowak",
"phone": "+48111222333",
"group_name": "Newsletter",
"message": "Hi {name}, thanks for signing up!",
"send_after": "2026-04-10T09:00:00"
},
{
"name": "Piotr Wiśniewski",
"phone": "+48444555666",
"group_name": "Newsletter"
}
]
}{
"created_count": 1,
"updated_count": 1,
"skipped_count": 0,
"skipped": [],
"messages_created_count": 1
}| Code | Status | Description |
|---|---|---|
| 201 | Created | Batch processed. Check created_count, updated_count, and skipped. |
| 400 | Bad Request | Validation error or batch exceeds 500. |
| 401 | Unauthorized | Invalid or inactive license / API key. |
Contact Group Endpoints
Creates a single contact group. Note: there is no uniqueness validation — creating a group with the same name twice will produce two separate groups. Use the bulk endpoint for idempotent group creation.
key + api_key in request body.
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | required | License key.6–12 chars |
| api_key | string | required | API key.12 chars |
| name | string | required | Group name. |
{
"key": "ABC123",
"api_key": "DEF456GHI789",
"name": "Summer Campaign 2026"
}{
"id": 42,
"name": "Summer Campaign 2026",
"created_by": 7
}| Code | Status | Description |
|---|---|---|
| 201 | Created | Group created. |
| 400 | Bad Request | Missing required fields. |
| 401 | Unauthorized | Invalid or inactive license / API key. |
Creates up to 200 contact groups in a single request. Idempotent — if a group with the same name already exists for this user, it is returned with status: "existed" and no duplicate is created.
key + api_key in request body.
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | required | License key.6–12 chars |
| api_key | string | required | API key.12 chars |
| groups | array | required | Array of objects with a name field.1–200 items |
{
"key": "ABC123",
"api_key": "DEF456GHI789",
"groups": [
{ "name": "VIP Clients" },
{ "name": "Newsletter" },
{ "name": "Inactive Users" }
]
}{
"groups": [
{ "name": "VIP Clients", "id": 10, "status": "existed" },
{ "name": "Newsletter", "id": 43, "status": "created" },
{ "name": "Inactive Users", "id": 44, "status": "created" }
]
}| Code | Status | Description |
|---|---|---|
| 201 | Created | Batch processed. Each group has status: created or existed. |
| 400 | Bad Request | Empty list or batch exceeds 200. |
| 401 | Unauthorized | Invalid or inactive license / API key. |
| Code | Status | Description |
|---|---|---|
| 200 | OK | Contact updated (phone already existed). |
| 201 | Created | New resource created or batch processed. |
| 400 | Bad Request | Validation error, missing fields, batch size exceeded, or all_or_nothing failure. |
| 401 | Unauthorized | Invalid or inactive license / API key. |
| 403 | Forbidden | Inactive license or daily SMS limit exceeded. |
| 404 | Not Found | License key or resource not found. |
| 409 | Conflict | Resource conflict (future use). |
| 429 | Too Many Requests | Rate limit exceeded. |
| 500 | Server Error | Internal server error. |
SMS delivery architecture
This API queues messages in the database — it is not an SMS gateway. Actual delivery is handled by the mobile companion app (Android) which polls for pending messages every 15 minutes, sending one SMS every 10 seconds via the device's SIM card. Plan your send times accordingly.