Sending messages¶

The client has three send methods, one per message type on the 1sms.az API.

Method	Use it for
`send_otp`	One-time passwords and verification codes
`send_notification`	Transactional messages such as order updates
`send_advertising`	Marketing and promotional campaigns

All three take the message text and a sender name. The sender name falls back to the one you gave the client, and you can override it on any call.

Phone numbers¶

Pass numbers in full international form without a plus sign, for example 994501234567. The client checks that a number is present before sending, and the API validates the format and reports any numbers it could not accept.

One-time passwords¶

result = client.send_otp("994501234567", "Your code is 123456")
print(result.message_id)

send_otp returns an OtpResult with the message id, the cost of the send, and your remaining balance.

Notifications¶

A single recipient is sent right away and comes back with a message id:

result = client.send_notification(["994501234567"], "Order shipped")
print(result.message_ids)

Two or more recipients are handled as a bulk task. The result carries a task_id you can poll later, along with counts and a list of any rejected numbers:

result = client.send_notification(
    ["994501234567", "994502223344", "994553334455"],
    "Weekend promotion",
)
print(result.task_id, result.sent_count, result.failed_count)

for item in result.rejected:
    print(item.number, "rejected:", item.reason)

See Delivery status for how to follow a task to completion.

Advertising¶

result = client.send_advertising(["994501234567"], "Big discounts this week")

Advertising sends share the same shape as notifications, including bulk tasks and the rejected list.

Choosing a sender name¶

client.send_notification(
    ["994501234567"],
    "Order shipped",
    sender_name="ShopName",
)

Limits¶

The client checks a few limits before it sends, so you get a clear OneSmsValidationError rather than a round trip that fails.

Message text is capped at 1530 characters.
A single send takes at most 10,000 recipients.
An idempotency key is at most 128 characters.

Avoiding duplicate sends¶

If a send might be retried, pass an idempotency key so it only goes out once. That has its own page: Retries and idempotency.