vendel

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2026 License: MIT Imports: 12 Imported by: 0

README

vendel-sdk-go

Official Go SDK for the Vendel SMS gateway API.

Install

go get github.com/JimScope/vendel-sdk-go

Usage

package main

import (
	"context"
	"fmt"

	vendel "github.com/JimScope/vendel-sdk-go"
)

func main() {
	client := vendel.NewClient("https://app.vendel.cc", "vk_your_api_key")

	// Send an SMS
	result, err := client.SendSMS(context.Background(), vendel.SendSMSRequest{
		Recipients: []string{"+1234567890"},
		Body:       "Hello from Vendel!",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.BatchID)

	// Check quota
	quota, err := client.GetQuota(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Printf("%d/%d SMS used\n", quota.SMSSentThisMonth, quota.MaxSMSPerMonth)
}

Webhook verification

isValid := vendel.VerifyWebhookSignature(rawBody, signatureHeader, "your_webhook_secret")

Requirements

  • Go >= 1.21

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsAPIError 

func IsAPIError(err error) bool

IsAPIError returns true if err is a *VendelError (or *QuotaError).

func IsQuotaError 

func IsQuotaError(err error) bool

IsQuotaError returns true if err is a *QuotaError.

func VerifyWebhookSignature 

func VerifyWebhookSignature(payload, signature, secret string) bool

VerifyWebhookSignature verifies a Vendel webhook X-Webhook-Signature header.

The signature is an HMAC-SHA256 hex digest computed over the raw JSON payload string using the webhook secret as the key.

Pass the raw request body as payload — do not re-marshal it.

Types

type BatchStatus added in v0.3.0 

type BatchStatus struct {
	BatchID      string          `json:"batch_id"`
	Total        int             `json:"total"`
	StatusCounts map[string]int  `json:"status_counts"`
	Messages     []MessageStatus `json:"messages"`
}

BatchStatus represents the delivery status of all messages in a batch.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the Vendel SMS gateway API client.

It uses an integration API key (vk_ prefix) for authentication.

func NewClient 

func NewClient(baseURL, apiKey string) *Client

NewClient creates a new Vendel API client.

func (*Client) GetBatchStatus added in v0.3.0 

func (c *Client) GetBatchStatus(ctx context.Context, batchID string) (*BatchStatus, error)

GetBatchStatus returns the delivery status of all messages in a batch.

func (*Client) GetMessageStatus added in v0.3.0 

func (c *Client) GetMessageStatus(ctx context.Context, messageID string) (*MessageStatus, error)

GetMessageStatus returns the delivery status of a single SMS message.

func (*Client) GetQuota 

func (c *Client) GetQuota(ctx context.Context) (*Quota, error)

GetQuota returns the current quota for the authenticated user.

func (*Client) ListContactGroups added in v0.3.0 

func (c *Client) ListContactGroups(ctx context.Context, page, perPage int) (*PaginatedResponse[ContactGroup], error)

ListContactGroups lists contact groups.

func (*Client) ListContacts added in v0.3.0 

func (c *Client) ListContacts(ctx context.Context, params ListContactsParams) (*PaginatedResponse[Contact], error)

ListContacts lists contacts with optional search and group filter.

func (*Client) ListDevices added in v0.4.0 

func (c *Client) ListDevices(ctx context.Context, opts *ListDevicesOptions) (*PaginatedDevices, error)

ListDevices lists registered devices with optional filters. A nil opts is treated as no filters.

func (*Client) ListMessages added in v0.4.0 

func (c *Client) ListMessages(ctx context.Context, opts *ListMessagesOptions) (*PaginatedMessages, error)

ListMessages lists SMS messages with optional filters. A nil opts is treated as no filters. From and To accept ISO8601 timestamps.

func (*Client) SendSMS 

func (c *Client) SendSMS(ctx context.Context, req SendSMSRequest) (*SendSMSResponse, error)

SendSMS sends an SMS to the specified recipients.

func (*Client) SendSMSTemplate added in v0.2.0 

func (c *Client) SendSMSTemplate(ctx context.Context, req SendSMSTemplateRequest) (*SendSMSResponse, error)

SendSMSTemplate sends an SMS using a saved template with variable interpolation. Reserved variables ({{name}}, {{phone}}) are auto-filled from contacts.

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(hc *http.Client)

SetHTTPClient overrides the default HTTP client used for requests.

type Contact added in v0.3.0 

type Contact struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	PhoneNumber string   `json:"phone_number"`
	Groups      []string `json:"groups"`
	Notes       string   `json:"notes"`
	Created     string   `json:"created"`
	Updated     string   `json:"updated"`
}

Contact represents a contact in the user's address book.

type ContactGroup added in v0.3.0 

type ContactGroup struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Created string `json:"created"`
	Updated string `json:"updated"`
}

ContactGroup represents a contact group.

type Device added in v0.4.0 

type Device struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DeviceType  string `json:"device_type"`
	PhoneNumber string `json:"phone_number"`
	Created     string `json:"created"`
	Updated     string `json:"updated"`
}

Device represents a registered SMS gateway device (Android phone or modem).

type ListContactsParams added in v0.3.0 

type ListContactsParams struct {
	Page    int
	PerPage int
	Search  string
	GroupID string
}

ListContactsParams holds parameters for listing contacts.

type ListDevicesOptions added in v0.4.0 

type ListDevicesOptions struct {
	Page       *int
	PerPage    *int
	DeviceType *string
}

ListDevicesOptions holds optional parameters for listing devices. All fields are pointers so callers can distinguish unset from zero.

type ListMessagesOptions added in v0.4.0 

type ListMessagesOptions struct {
	Page      *int
	PerPage   *int
	Status    *string
	DeviceID  *string
	BatchID   *string
	Recipient *string
	From      *string
	To        *string
}

ListMessagesOptions holds optional parameters for listing messages. All fields are pointers so callers can distinguish unset from zero. From and To accept ISO8601 timestamps.

type MessageStatus added in v0.3.0 

type MessageStatus struct {
	ID           string `json:"id"`
	BatchID      string `json:"batch_id"`
	Recipient    string `json:"recipient"`
	FromNumber   string `json:"from_number"`
	Body         string `json:"body"`
	Status       string `json:"status"`
	MessageType  string `json:"message_type"`
	ErrorMessage string `json:"error_message"`
	DeviceID     string `json:"device_id"`
	SentAt       string `json:"sent_at"`
	DeliveredAt  string `json:"delivered_at"`
	Created      string `json:"created"`
	Updated      string `json:"updated"`
}

MessageStatus represents the delivery status of a single SMS message.

type PaginatedDevices added in v0.4.0 

type PaginatedDevices = PaginatedResponse[Device]

PaginatedDevices is a paginated response of devices.

type PaginatedMessages added in v0.4.0 

type PaginatedMessages = PaginatedResponse[MessageStatus]

PaginatedMessages is a paginated response of messages.

type PaginatedResponse added in v0.3.0 

type PaginatedResponse[T any] struct {
	Items      []T `json:"items"`
	Page       int `json:"page"`
	PerPage    int `json:"per_page"`
	TotalItems int `json:"total_items"`
	TotalPages int `json:"total_pages"`
}

PaginatedResponse is a generic paginated API response.

type Quota 

type Quota struct {
	Plan              string `json:"plan"`
	SMSSentThisMonth  int    `json:"sms_sent_this_month"`
	MaxSMSPerMonth    int    `json:"max_sms_per_month"`
	DevicesRegistered int    `json:"devices_registered"`
	MaxDevices        int    `json:"max_devices"`
	ResetDate         string `json:"reset_date"`
}

Quota represents the user's current plan limits and usage.

type QuotaError 

type QuotaError struct {
	VendelError
	Limit     int
	Used      int
	Available int
}

QuotaError is returned when a quota limit is exceeded (HTTP 429).

type SendSMSRequest 

type SendSMSRequest struct {
	Recipients []string `json:"recipients"`
	Body       string   `json:"body"`
	DeviceID   string   `json:"device_id,omitempty"`
	GroupIDs   []string `json:"group_ids,omitempty"`
}

SendSMSRequest is the payload for sending an SMS.

type SendSMSResponse 

type SendSMSResponse struct {
	BatchID         string   `json:"batch_id"`
	MessageIDs      []string `json:"message_ids"`
	RecipientsCount int      `json:"recipients_count"`
	Status          string   `json:"status"`
}

SendSMSResponse is returned after a successful send.

type SendSMSTemplateRequest added in v0.2.0 

type SendSMSTemplateRequest struct {
	Recipients []string          `json:"recipients"`
	TemplateID string            `json:"template_id"`
	Variables  map[string]string `json:"variables,omitempty"`
	DeviceID   string            `json:"device_id,omitempty"`
	GroupIDs   []string          `json:"group_ids,omitempty"`
}

SendSMSTemplateRequest is the payload for sending an SMS using a saved template. Reserved variables ({{name}}, {{phone}}) are auto-filled from contacts.

type VendelError 

type VendelError struct {
	StatusCode int
	Message    string
	Detail     map[string]any
}

VendelError is the base error returned by the SDK.

func (*VendelError) Error 

func (e *VendelError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.