# Submit asynchronous bulk SMS job
URL: /docs/api-reference/bulk-campaign-messaging/submitBulkJob

## POST `/api/v1/public/sms/bulk/jobs`

**Summary:** Submit asynchronous bulk SMS job
**Operation ID:** `submitBulkJob`

Submits a bulk campaign for asynchronous processing. Recipients can be supplied as an inline array of phone numbers or pre-uploaded via file. Unit credits are reserved upfront and unconsumed units are refunded if cancelled prior to dispatch.

**Authentication:** `X-Api-Key: sk_live_...` or `Authorization: Bearer sk_live_...`

### Request Body (`application/json`)

```json
{
  "type": "object",
  "required": [
    "message"
  ],
  "properties": {
    "jobName": {
      "type": "string",
      "example": "November Promo Campaign"
    },
    "message": {
      "type": "string",
      "example": "Special offer! Use code PROMO50 today."
    },
    "senderId": {
      "type": "string",
      "maxLength": 11,
      "example": "SMSPRO"
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "+233241234567",
        "+233501234567"
      ]
    },
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "Pre-uploaded CSV or Excel file ID"
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time"
    },
    "deliveryCallbackUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}
```

### Responses

- **`202`**: Bulk job queued for asynchronous dispatch

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "example": "success"
    },
    "message": {
      "type": "string",
      "example": "Bulk job queued"
    },
    "data": {
      "type": "object",
      "properties": {
        "batchId": {
          "type": "string",
          "example": "batch-7f9a2e41-0023"
        },
        "jobName": {
          "type": "string",
          "example": "November Promo Campaign"
        },
        "recipientCount": {
          "type": "integer",
          "example": 2500
        },
        "status": {
          "type": "string",
          "example": "QUEUED"
        },
        "totalUnits": {
          "type": "integer",
          "example": 2500
        }
      }
    }
  }
}
```
- **`400`**: Invalid or malformed request syntax
- **`401`**: Authentication failed or API key missing
- **`422`**: Validation error or invalid input parameters