SMSTunnel for Go

go get github.com/narcisbodea/smstunnel-go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/narcisbodea/smstunnel-go"
)

func main() {
	client, err := smstunnel.NewClient(os.Getenv("SMSTUNNEL_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	res, err := client.SendSMS(context.Background(), "+14155550123", "Your order #1042 has shipped.")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.MessageID) // keep it to look up the status later
}

res, err := client.SendSMS(ctx,
	"+14155550123",      // international format; one number per call
	"See you at 10:30.", // up to 1600 characters
	smstunnel.WithDeviceID("6aea3248fedd7cccac9abf42"),       // the phone that sends it (Phones → Copy); leave it out to let SMSTunnel pick one of yours
	smstunnel.WithCountryCode("+40"),                         // completes numbers written without + or 00, like 0721 123 456
	smstunnel.WithIdempotencyKey("appointment-981-reminder"), // makes a retry safe, see below
)

res.MessageID // string
res.Queued    // true when no phone of yours was online: the text waits and goes out when one is back
res.Branded   // true when the Free plan added its short line to the text
res.Replayed  // true when this is the stored answer to an earlier call with the same idempotency key

_, err := client.SendSignInCode(ctx, "+14155550123", "Your sign-in code is 482913")

status, err := client.GetMessageStatus(ctx, res.MessageID) // needs sms:read

status.State         // smstunnel.StatePending, StateSent, StateDelivered, StateFailed or StateUnconfirmed
status.State.Final() // true once it won't change: delivered, failed or unconfirmed
status.SentAt        // *time.Time
status.ErrorMessage  // why it failed

phones, err := client.ListPhones(ctx)
for _, phone := range phones {
	fmt.Println(phone.ID, phone.Name, phone.Online)
}

usage, err := client.GetUsage(ctx)
usage.Plan                 // "free", "twofa" (Starter), "standard", "pro" (Professional) or "enterprise"
usage.Used.SMSClean        // texts sent today
usage.Remaining.SMSClean   // texts left today: a Quota, smstunnel.Unlimited when there is no limit
usage.Remaining.TwoFAClean // sign-in codes left today

page, err := client.ListReceivedTexts(ctx, smstunnel.ReceivedTextsQuery{
	Since: time.Now().Add(-24 * time.Hour),
	Phone: "+14155550123", // only from this sender
	Limit: 20,             // 1 to 100
	Page:  1,
})
for _, text := range page.Texts { // newest first
	fmt.Println(text.ReceivedAt.Format(time.Kitchen), text.Sender, text.Message)
}
page.HasMore // ask for the next page

cursor, err := client.NewReceivedTextsCursor(smstunnel.ReceivedTextsCursorOptions{Since: time.Now()})
for {
	texts, err := cursor.Next(ctx)
	if err != nil {
		log.Print(err) // nothing is lost: the next call asks again
	}
	for _, text := range texts {
		fmt.Println(text.Sender, text.Message)
	}
	time.Sleep(10 * time.Second)
}

sms, err := smstunnel.NewClient(os.Getenv("SMSTUNNEL_API_KEY"), smstunnel.WithDefaultCountryCode("+40"))
if err != nil {
	log.Fatal(err)
}

http.HandleFunc("POST /orders/{id}/shipped", func(w http.ResponseWriter, r *http.Request) {
	order, err := orders.MarkShipped(r.Context(), r.PathValue("id"))
	if err != nil {
		http.Error(w, err.Error(), http.StatusNotFound)
		return
	}
	_, err = sms.SendSMS(r.Context(), order.Phone, "Your order #"+order.ID+" has shipped.",
		smstunnel.WithIdempotencyKey("order-"+order.ID+"-shipped"))
	if err != nil {
		log.Printf("the shipping text for order %s did not go out: %v", order.ID, err)
	}
	w.WriteHeader(http.StatusNoContent)
})

_, err := client.SendSMS(ctx, number, text, smstunnel.WithIdempotencyKey(textID))

var apiErr *smstunnel.APIError
var connErr *smstunnel.ConnectionError
switch {
case err == nil:
case errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusTooManyRequests && apiErr.RetryAfter > 0:
	time.Sleep(apiErr.RetryAfter) // then try again, with the same idempotency key
case errors.As(err, &apiErr) && apiErr.Code == smstunnel.CodePermissionRequired:
	log.Printf("the SMSTunnel key lacks %s", apiErr.Permission)
case errors.As(err, &connErr):
	log.Printf("no answer (timeout: %v): retry only with the same idempotency key", connErr.Timeout())
default:
	log.Print(err)
}

client, err := smstunnel.NewClient(os.Getenv("SMSTUNNEL_API_KEY"),
	smstunnel.WithDefaultCountryCode("+40"),        // for numbers written without + or 00; a text's WithCountryCode wins
	smstunnel.WithTimeout(15*time.Second),          // per call; the default is 30 seconds, 0 turns it off
	smstunnel.WithHTTPClient(myHTTPClient),         // your transport, proxy or TLS settings
	smstunnel.WithUserAgentSuffix("my-tool/2.1"),   // added to the User-Agent header
	smstunnel.WithBaseURL("http://127.0.0.1:3141"), // a test server; the default is https://smstunnel.io
)