API reference

Base URL

https://srv.msgflash.com

All public endpoints are prefixed with /api/v1/. Examples:

https://srv.msgflash.com/api/v1/messages/send
https://srv.msgflash.com/api/v1/templates
https://srv.msgflash.com/api/v1/contacts
https://srv.msgflash.com/api/v1/billing/usage

Authentication

All requests to /api/v1/* require a MsgFlash API key in the x-api-key header.

curl https://srv.msgflash.com/api/v1/usage \
  -H "x-api-key: msgf_live_your_api_key_here"

See Authentication for exact header format and security requirements.

Team workspace (`msgf_team_…`)

Team API keys require X-Team-Id matching the key’s team; workspace /api/v1/* routes then use the team’s shared data and the team owner’s plan. Personal keys must not send X-Team-Id (TEAM_KEY_REQUIRED). Account, compact usage, and most billing reads require a personal key (TEAM_KEY_NOT_ALLOWED with a team key). Full rules: Team context.

Rate limiting

Limit	Value
Requests per second	10 req/s
Scope	Per API key
Error code	`API_RATE_LIMIT_EXCEEDED`

If the limit is exceeded:

{
  "error": {
    "code": "API_RATE_LIMIT_EXCEEDED",
    "message": "Too many API requests"
  }
}

The real-time rate limit is separate from the monthly monthlyApiRequestQuota. You can stay under your monthly quota and still receive 429 if you exceed 10 req/s.

Response format

Success

All successful responses are wrapped in data.

{
  "data": {
    "id": "uuid",
    "status": "queued"
  }
}

For simple lists:

{
  "data": [
    { "id": "..." },
    { "id": "..." }
  ]
}

For paginated lists:

{
  "data": {
    "messages": [],
    "nextCursor": null,
    "hasMore": false
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Message not found"
  }
}

See Error codes for the main codes.

Available endpoints

Messages

Method	Endpoint	Description
`POST`	`/api/v1/messages/send`	Send an instant message
`POST`	`/api/v1/messages/schedule`	Schedule a message
`GET`	`/api/v1/messages`	List messages
`GET`	`/api/v1/messages/{id}`	Message details

Campaigns

Method	Endpoint	Description
`POST`	`/api/v1/campaigns`	Create a campaign
`GET`	`/api/v1/campaigns/{id}`	Campaign details
`GET`	`/api/v1/campaigns/{id}/stats`	Delivery statistics
`POST`	`/api/v1/campaigns/{id}/pause`	Pause a campaign
`POST`	`/api/v1/campaigns/{id}/resume`	Resume a campaign

Templates

Method	Endpoint	Description
`GET`	`/api/v1/templates`	List templates
`POST`	`/api/v1/templates`	Create a template
`GET`	`/api/v1/templates/{id}`	Template details
`PUT`	`/api/v1/templates/{id}`	Update a template
`DELETE`	`/api/v1/templates/{id}`	Delete a template
`POST`	`/api/v1/templates/{id}/preview`	Preview a template render

Contacts

Method	Endpoint	Description
`GET`	`/api/v1/contacts`	List contacts
`POST`	`/api/v1/contacts`	Create a contact
`GET`	`/api/v1/contacts/{id}`	Contact details
`PUT`	`/api/v1/contacts/{id}`	Update a contact
`DELETE`	`/api/v1/contacts/{id}`	Delete a contact
`POST`	`/api/v1/contacts/bulk-delete`	Bulk delete contacts
`GET`	`/api/v1/contacts/bulk-jobs`	List bulk contact jobs
`GET`	`/api/v1/contacts/bulk-jobs/{jobId}`	Bulk job details
`GET`	`/api/v1/contacts/bulk-jobs/{jobId}/progress`	Bulk job progress
`POST`	`/api/v1/contacts/bulk-jobs/{jobId}/cancel`	Cancel a bulk job

Contact groups

Method	Endpoint	Description
`GET`	`/api/v1/contacts/groups`	List groups
`POST`	`/api/v1/contacts/groups`	Create a group
`GET`	`/api/v1/contacts/groups/{groupId}`	Group details
`PUT`	`/api/v1/contacts/groups/{groupId}`	Update a group
`DELETE`	`/api/v1/contacts/groups/{groupId}`	Delete a group
`POST`	`/api/v1/contacts/groups/{groupId}/members`	Add members
`DELETE`	`/api/v1/contacts/groups/{groupId}/members`	Remove members
`GET`	`/api/v1/contacts/groups/{groupId}/members`	List members
`GET`	`/api/v1/contacts/{id}/groups`	List groups for a contact

Webhooks

Method	Endpoint	Description
`GET`	`/api/v1/webhooks`	List your webhook endpoints
`POST`	`/api/v1/webhooks`	Create a webhook endpoint
`DELETE`	`/api/v1/webhooks/{id}`	Delete a webhook endpoint

WhatsApp statuses

Method	Endpoint	Description
`POST`	`/api/v1/statuses`	Publish a WhatsApp status

Instances

Method	Endpoint	Description
`GET`	`/api/v1/instances`	List instances
`GET`	`/api/v1/instances/{id}`	Instance details
`GET`	`/api/v1/instances/{id}/state`	Live instance state

Billing public read-only

Method	Endpoint	Description
`GET`	`/api/v1/usage`	Compact usage summary
`GET`	`/api/v1/billing/plans`	Plan catalog
`GET`	`/api/v1/billing/subscription`	Current subscription and billing period
`GET`	`/api/v1/billing/usage`	Usage, limits, and features
`GET`	`/api/v1/billing/payments`	Payment history

Getting Started

Guides

API Reference · Teams

API Reference · Instances

API Reference · Messages

API Reference · Campaigns

API Reference · Templates

API Reference · Contacts

API Reference · Groups

API Reference · Number Lookups

API Reference · Webhooks

API Reference · Billing

Resources

Base URL

Authentication

Team workspace (`msgf_team_…`)

Rate limiting

Response format

Success

Error

Available endpoints

Messages

Campaigns

Templates

Contacts

Contact groups

Webhooks

WhatsApp statuses

Instances

Billing public read-only

​Base URL

​Authentication

​Team workspace (msgf_team_…)

​Rate limiting

​Response format

​Success

​Error

​Available endpoints

​Messages

​Campaigns

​Templates

​Contacts

​Contact groups

​Webhooks

​WhatsApp statuses

​Instances

​Billing public read-only

Base URL

Authentication

Team workspace (`msgf_team_…`)

Rate limiting

Response format

Success

Error

Available endpoints

Messages

Campaigns

Templates

Contacts

Contact groups

Webhooks

WhatsApp statuses

Instances

Billing public read-only