Send email, SMS and WhatsApp
from the system you already run.

curl -X POST https://besends.com/api/sms/send \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact": [
      { "number": "8801712345678", "message": "Your order #4417 is out for delivery." }
    ]
  }'

{
  "success": true,
  "message": "Sms dispatch request created successfully",
  "data": [
    {
      "id": 84213,
      "status": "pending",
      "contact_id": 5591,
      "created_at": "2026-09-07 14:02:11"
    }
  ]
}

{
  "status": "error",
  "message": "API key is required. Provide via header (Api-key) or URL parameter (api_key)",
  "error": "Invalid Api Key"
}

{
  "status": "error",
  "error": "Your Subscription Is Expired! Buy A New Plan"
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.subject": ["The contact.0.subject field is required."],
    "contact.0.message": ["The contact.0.message field is required."]
  }
}

<?php
// Called by your ERP the moment an invoice passes its due date.
function notifyOverdue(array $invoice): void
{
    $body = [
        'contact' => [[
            'number'  => $invoice['phone'],
            'message' => sprintf(
                'Invoice %s for BDT %s was due on %s. Pay at %s',
                $invoice['number'],
                number_format($invoice['amount']),
                $invoice['due_date'],
                'https://yourcompany.com.bd/pay'
            ),
        ]],
    ];

    $ch = curl_init(getenv('CONNECTS_BASE') . '/sms/send');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            'Api-key: ' . getenv('CONNECTS_API_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_TIMEOUT    => 15,
    ]);

    $response = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    // Messaging must never break invoicing. Log and carry on.
    if ($status !== 200) {
        error_log("BeSends overdue notice failed for {$invoice['number']}: {$response}");
    }
}

import os, time, requests

BASE  = os.environ["CONNECTS_BASE"]        # https://…/api
KEY   = os.environ["CONNECTS_API_KEY"]
CHUNK = 500                                 # recipients per request
PAUSE = 1.2                                 # seconds between requests

def send_all(recipients, body_for):
    """recipients: iterable of dicts. body_for(r) -> message string."""
    queued, failed = [], []

    for i in range(0, len(recipients), CHUNK):
        batch = recipients[i:i + CHUNK]
        payload = {"contact": [
            {"number": r["phone"], "message": body_for(r)} for r in batch
        ]}

        for attempt in range(3):
            res = requests.post(
                f"{BASE}/sms/send",
                headers={"Api-key": KEY,
                         "Content-Type": "application/json",
                         "Accept": "application/json"},
                json=payload, timeout=60,
            )

            if res.status_code == 429:          # rate limited — wait it out
                time.sleep(20)
                continue
            if res.status_code == 422:          # our payload is wrong; do not retry
                failed.append((i, res.json()))
                break
            if res.ok and res.json().get("success"):
                queued += [row["id"] for row in res.json()["data"]]
                break
            time.sleep(3 * (attempt + 1))       # 5xx — back off and try again
        else:
            failed.append((i, "gave up after 3 attempts"))

        time.sleep(PAUSE)

    return queued, failed

// 1. Email everyone, and keep the log ids alongside the recipient.
const emailed = await post('/email/send', {
  contact: audience.map((p) => ({
    email: p.email,
    subject: 'Your September statement',
    message: renderStatement(p),
  })),
});

const pairs = audience.map((p, i) => ({ person: p, logId: emailed.data[i].id }));

// 2. Give the queue time to resolve, then check each one.
await new Promise((r) => setTimeout(r, 30_000));

const missed = [];
for (const { person, logId } of pairs) {
  const log = await get(`/get/email/${logId}`);
  if (log.data.status === 'fail') missed.push(person);
}

// 3. SMS only those, in one call.
if (missed.length) {
  await post('/sms/send', {
    contact: missed.map((p) => ({
      number: p.phone,
      message: `We could not email your September statement. Collect it at ${p.branch}.`,
    })),
  });
}

You are integrating the BeSends messaging API into an existing system.

## Fill these in before you start
- Language / framework: [e.g. Laravel 10, Django 5, Spring Boot 3, .NET 8, Node + Express]
- What triggers a message: [e.g. an invoice passes its due date; a student's fee is unpaid]
- Which channels: [SMS / email / WhatsApp — pick the ones you need]
- Roughly how many messages per send: [e.g. 1, or 40,000 in three days]

## The API

Base URL: https://besends.com/api
Transport: HTTPS, JSON. Send `Content-Type: application/json` and `Accept: application/json`.
Auth: header `Api-key: <key>` on every request. Read the key from the environment
variable CONNECTS_API_KEY. Never hard-code it, never send it to a browser or a mobile app,
never put it in a URL.

Rate limit: 60 requests per minute per IP. `contact` is an array — batch many recipients
into one request rather than looping one request per recipient.

### POST /sms/send
{
  "contact": [
    {
      "number": "8801712345678",              // required, string, max 255
      "message": "text",                       // required, string
      "schedule_at": "2026-09-08 09:00:00",    // optional, exactly Y-m-d H:i:s
      "gateway_identifier": "gateway-uid",     // optional
      "sms_type": "transactional"              // optional
    }
  ],
  "method": "api"                              // optional, top level: "api" or "android"
}

### POST /email/send
{
  "contact": [
    {
      "email": "person@example.com",           // required, valid email, max 255
      "subject": "text",                       // required, max 255
      "message": "<p>HTML allowed</p>",         // required
      "sender_name": "Acme Accounts",          // optional
      "reply_to_email": "reply@example.com",   // optional
      "schedule_at": "2026-09-08 09:00:00",    // optional
      "gateway_identifier": "gateway-uid"      // optional, must be an active email gateway uid
    }
  ]
}
Attachments require a multipart request instead of JSON, with fields named
contact[0][email], contact[0][subject], contact[0][message] and files at attachments[0].
Allowed: pdf, doc, docx, xls, xlsx, csv, txt, png, jpg, jpeg, gif, zip, rar, svg, webp.

### POST /whatsapp/send
{
  "contact": [
    {
      "number": "8801712345678",               // required
      "message": "text or media caption",      // required
      "media": "document",                     // optional: image | audio | video | document
      "url": "https://public.example/file.pdf",// required when media is set; must be publicly fetchable
      "filename": "Statement.pdf",             // optional
      "schedule_at": "2026-09-08 09:00:00",    // optional
      "gateway_identifier": "gateway-uid"      // optional
    }
  ]
}

### GET /get/sms/{id} — also /get/email/{id} and /get/whatsapp/{id}
Returns one log record. `status` is one of:
pending | schedule | processing | delivered | fail | cancel

## Responses

Success (HTTP 200):
{ "success": true, "message": "…", "data": [ { "id": 84213, "status": "pending", … } ] }

Validation failure (HTTP 422):
{ "success": false, "message": "Validation failed",
  "errors": { "contact.0.message": ["The contact.0.message field is required."] } }

Auth failure (HTTP 403) — NOTE THE DIFFERENT SHAPE, it comes from middleware:
{ "status": "error", "error": "Invalid Api Key" }
or
{ "status": "error", "error": "Your Subscription Is Expired! Buy A New Plan" }

## Write the integration with these rules

1. One reusable client class/module. Base URL and API key come from configuration, never
   from literals in the calling code.
2. Handle BOTH response envelopes. Branch on the HTTP status code first, then read the body:
   403 -> auth or expired plan, do NOT retry, surface loudly to an operator
   422 -> our payload is wrong, do NOT retry, log the `errors` object verbatim
   429 -> rate limited, wait and retry with exponential backoff
   5xx -> retry up to 3 times with backoff, then give up and log
   200 -> read `data[].id` and store each id against the record that caused the message
3. Store the returned log id alongside your own record. That id is the only way to ask later
   what happened to the message.
4. Treat a 200 as "accepted", never as "delivered". If the caller needs the real outcome,
   poll GET /get/{channel}/{id} after a delay, with backoff — never in a tight loop.
5. Messaging must never break the calling process. Wrap every call so that a failure is
   logged and the invoice/order/enrolment still completes.
6. Batch: chunk recipients (about 500 per request is sensible) and pause briefly between
   chunks to stay inside 60 requests per minute.
7. Set an explicit HTTP timeout (30s is reasonable, 60s when attaching files).
8. Phone numbers: normalise to international format without a leading +, e.g. 8801712345678.
9. Timestamps for schedule_at must be exactly Y-m-d H:i:s or the request is rejected.
10. Do not invent endpoints, fields or query parameters. Everything available is above; if
    something you need is not listed, say so rather than guessing.

Now write the integration, including the error handling and a short usage example.