Email API documentation

How request_id works

1. Preview the counts with action=preview. No request_id is needed and no records are deleted.
2. Generate a unique request_id for a new deletion, for example a UUID. Save it before sending action=delete.
3. For retries, timeouts or HTTP 202, reuse the same API key, history endpoint, request_id and include_linked value. Never generate a new ID automatically after an error.
4. When completed=true, the operation is finished. Reusing its ID returns the same result instead of deleting newly arrived records. Use a new ID only for a deliberately new cleanup.

request_id identifies your deletion operation, not an individual SMS. Allowed format: 16–128 ASCII letters, digits, hyphens or underscores. A UUID generated with crypto.randomUUID() is suitable.

Deletion runs in batches. HTTP 202 with continue_required=true means you must repeat action=delete after 3 seconds. There is no background cron. action=status only reads progress, even when its HTTP status is 200.

Deletion and status examples

Replace the sample request_id with your own unique value before starting. The following delete requests change real account history; they are not previews.

curl -X POST "https://api.smsmobileapi.com/delete-history-email/" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  -d "action=delete" -d "include_linked=0" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

curl -X POST "https://api.smsmobileapi.com/delete-history-email/" \
  -H "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN" \
  -d "action=delete" -d "include_linked=0" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

curl -G "https://api.smsmobileapi.com/delete-history-email/" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  -d "action=status" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

GET also accepts action=preview or action=delete. POST is recommended: URL parameters can leak into browser history and server logs. Never place a deletion URL in a public link, image or prefetch.

For POST, send all parameters in the form body or a JSON object, never in the query string. Unknown parameters are rejected; date or mobile filters are not supported.

Authentication for history endpoints

Use apikey or an Authorization: Bearer access token issued by SMSMobileAPI OAuth2. Do not send a refresh token or an API key as a Bearer token. Expired tokens are refused.

When scopes are set, history:read allows preview/status and history:delete also allows deletion. Restrictions on both the token and OAuth client apply. Legacy tokens without scopes retain their existing account access.

OAuth2 selects the unique primary API key. If several primary keys exist, also provide apikey to select one belonging to the account. Secondary keys never grant access to the primary key history.

Read the response before continuing

count_delete is the cumulative number removed by this operation. selected_at_start is the initial selection; protected_at_start counts excluded records. Use preview.linked_or_processing to count linked records even when include_linked=1.

{
    "result": {
        "error": 0,
        "history": "email",
        "action": "delete",
        "request_id": "6d54ac58-41f1-4fbc-9a39-6e6c86089451",
        "status": "processing",
        "completed": false,
        "count_delete": 100,
        "total_before": 250,
        "selected_at_start": 200,
        "protected_at_start": 50,
        "include_linked": 0,
        "continue_required": true,
        "message": "Repeat GET or POST with the same request_id and include_linked to continue. Status requests do not run deletion."
    }
}

• 200 with completed=true: finished. A 200 preview or status response alone does not prove completion.
• 400 INVALID_REQUEST_ID: check the format. 404 REQUEST_NOT_FOUND: no operation exists for this ID, API key and history.
• 401: invalid or expired credentials. 403: insufficient OAuth scope or unauthorized account.
• 409 HISTORY_BUSY: another cleanup is running; continue it from the original client. 409 INCLUDE_LINKED_CONFLICT: restore the original include_linked value.
• 409 OAUTH_ACCOUNT_AMBIGUOUS: provide an API key belonging to this account.
• 503 or network interruption: some batches may already be completed. Check configuration, then retry with the original request_id. Do not create a replacement operation automatically.