go-netgsm

An idiomatic Go client for the NetGSM SMS REST API (v2). Context-aware, typed errors, fully tested, standard-library only.

Why

There is no well-maintained, idiomatic Go client for NetGSM — most projects hand-roll the HTTP call every time. This one targets the modern REST v2 API (https://api.netgsm.com.tr/sms/rest/v2), uses HTTP Basic auth, and turns NetGSM's numeric result codes into typed errors you can match with errors.Is.

Install

go get github.com/YusufDrymz/go-netgsm

Usage

client := netgsm.New(netgsm.Config{
    UserCode: "your-usercode",
    Password: "your-api-password",
    Header:   "YOUR_HEADER", // approved sender name
}, netgsm.WithTimeout(10*time.Second))

res, err := client.Send(ctx, netgsm.SMS{
    To:   []string{"5301112233", "5304445566"},
    Text: "Merhaba dünya",
})
if err != nil {
    if errors.Is(err, netgsm.ErrSystem) {
        // provider-side error, safe to retry
    }
    return
}
fmt.Println("job id:", res.JobID)

Scheduled send and one-time passwords:

client.Send(ctx, netgsm.SMS{To: to, Text: msg,
    StartAt: time.Now().Add(time.Hour)}) // schedule
client.SendOTP(ctx, netgsm.OTP{To: "5301112233", Text: "Kod: 1234"})

Errors

Every NetGSM result code maps to a typed error. Match the family with errors.Is, or read the concrete code with errors.As:

Sentinel	Codes	Meaning
ErrMessageTooLong	20	message text invalid / too long
ErrInvalidCredentials	30	bad credentials or no API permission
ErrInvalidHeader	40, 41	sender header not defined
ErrIYSFilter	50, 51	İYS-controlled sending not allowed
ErrInvalidParams	70	invalid or missing parameters
ErrDuplicateLimit	85	duplicate-send rate limit hit
ErrSystem	100	provider system error (Retryable: true)

var apiErr *netgsm.Error
if errors.As(err, &apiErr) && apiErr.Retryable {
    // back off and retry
}

Options

Option	Default
WithTimeout(d)	30s
WithEncoding(enc)	TR (use ASCII for GSM-7)
WithHTTPClient(h)	http.Client{Timeout: 30s}
WithBaseURL(u)	https://api.netgsm.com.tr

See examples/.

🇹🇷 Türkçe

NetGSM SMS REST API (v2) için idiomatic bir Go istemcisi. Context destekli, typed error'lı, tam test edilmiş, sıfır dış bağımlılık.

Kurulum: go get github.com/YusufDrymz/go-netgsm

client := netgsm.New(netgsm.Config{
    UserCode: "kullanici", Password: "api-sifresi", Header: "BASLIK",
})
res, err := client.Send(ctx, netgsm.SMS{To: []string{"5301112233"}, Text: "Merhaba"})

NetGSM dönüş kodları typed error'a çevrilir: ErrInvalidCredentials (30), ErrInvalidHeader (40/41), ErrIYSFilter (50/51), ErrInvalidParams (70), ErrDuplicateLimit (85), ErrSystem (100, retryable). errors.Is ile aile, errors.As ile ham kod kontrol edilir. Zamanlanmış gönderim (StartAt/StopAt) ve OTP (SendOTP) desteklenir.

License

MIT — see LICENSE.