Help us shape the future of Go! Take the 2026 Go Developer Survey

sendimessage

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 2026 License: MIT Imports: 17 Imported by: 0

README

SendiMessage SDK for Go

Stdlib-only client (Go ≥ 1.21) for the SendiMessage API. Server-side use — the key pair grants full messaging access.

Install

go get github.com/sendimessage/sendimessage-go

Quick start

import (
    "context"

    sendimessage "github.com/sendimessage/sendimessage-go"
)

client := sendimessage.New(apiKey, apiSecret) // from the account portal
ctx := context.Background()

// Text
msg, err := client.SendMessage(ctx, sendimessage.SendMessageParams{
    Number:  "+15551234567",
    Content: "Hello!",
})
// msg.MessageHandle, msg.Status == "QUEUED"

// Photo / video: upload first, then send the returned URL
url, err := client.UploadMedia(ctx, "photo.jpg")
_, err = client.SendMessage(ctx, sendimessage.SendMessageParams{
    Number:   "+15551234567",
    MediaURL: url,
})

// Delivery status
status, err := client.GetStatus(ctx, msg.MessageHandle)

Webhooks

_, err := client.CreateWebhook(ctx, sendimessage.WebhookParams{
    URL:    "https://example.com/hooks/sendimessage",
    Events: []string{"receive", "outbound"},
    Secret: "my-shared-secret",
})

// In your webhook handler (rawBody = the body exactly as received):
ok := sendimessage.VerifyWebhookSignature("my-shared-secret", rawBody,
    r.Header.Get("X-SMSBridge-Signature"))

Errors

Any non-2xx response returns *sendimessage.APIError with Status (HTTP code), Message (API error text) and Body (raw response).

var apiErr *sendimessage.APIError
if errors.As(err, &apiErr) && apiErr.Status == 422 {
    log.Println(apiErr.Message) // e.g. "Contact has opted out of messages"
}

Surface

Messages: SendMessage, GetStatus, ListMessages, GetMessage, UploadMedia, UploadMediaReader. Lookup: Lookup — iMessage or SMS. Contacts: ListContacts, CreateContact, GetContact, UpdateContact, DeleteContact, SetOptOut, RecheckContact. Lines: ListLines, UpdateLine, GetCallForwarding, SetCallForwarding. Conversations: ListConversations, ListConversationMessages, MarkConversationRead. Webhooks: ListWebhooks, CreateWebhook, ReplaceWebhooks, DeleteWebhook.

Full API reference: the Postman collection at https://sendimessage.com/postman_collection.json.

Documentation

Overview

Package sendimessage is the SendiMessage SDK — send iMessage/SMS through the SendiMessage API. Server-side use: the key pair grants full messaging access. 

client := sendimessage.New(apiKey, apiSecret)
msg, err := client.SendMessage(ctx, sendimessage.SendMessageParams{
	Number:  "+15551234567",
	Content: "Hello!",
})

Index

Constants

View Source 
const DefaultBaseURL = "https://api.sendimessage.com/v1"

Variables

This section is empty.

Functions

func VerifyWebhookSignature 

func VerifyWebhookSignature(secret string, rawBody []byte, signature string) bool

VerifyWebhookSignature checks the X-SMSBridge-Signature header of an incoming webhook: hex HMAC-SHA256 of the raw request body with the webhook's secret. Pass the body exactly as received.

Types

type APIError 

type APIError struct {
	Status  int
	Message string
	Body    []byte
}

APIError is returned for any non-2xx API response.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

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

Client talks to the SendiMessage public API (X-API-Key / X-API-Secret).

func New 

func New(apiKey, apiSecret string, opts ...Option) *Client

New creates a Client with the key pair from the account portal.

func (*Client) CreateContact 

func (c *Client) CreateContact(ctx context.Context, props Object) (Object, error)

func (*Client) CreateWebhook 

func (c *Client) CreateWebhook(ctx context.Context, params WebhookParams) (Object, error)

func (*Client) DeleteContact 

func (c *Client) DeleteContact(ctx context.Context, number string) (Object, error)

func (*Client) DeleteWebhook 

func (c *Client) DeleteWebhook(ctx context.Context, webhookURL string) (Object, error)

func (*Client) GetCallForwarding 

func (c *Client) GetCallForwarding(ctx context.Context, lineHandle string) (Object, error)

func (*Client) GetContact 

func (c *Client) GetContact(ctx context.Context, number string) (Object, error)

GetContact fetches a contact; number is the E.164 number or contact_handle.

func (*Client) GetMessage 

func (c *Client) GetMessage(ctx context.Context, messageHandle string) (*HistoryMessage, error)

GetMessage returns one history message by its handle.

func (*Client) GetStatus 

func (c *Client) GetStatus(ctx context.Context, messageHandle string) (*OutboundMessage, error)

GetStatus reports the current status of a message by its handle.

func (*Client) ListContacts 

func (c *Client) ListContacts(ctx context.Context, query url.Values) (Object, error)

func (*Client) ListConversationMessages 

func (c *Client) ListConversationMessages(ctx context.Context, conversationHandle string, query url.Values) (Object, error)

func (*Client) ListConversations 

func (c *Client) ListConversations(ctx context.Context, query url.Values) (Object, error)

func (*Client) ListLines 

func (c *Client) ListLines(ctx context.Context) (Object, error)

func (*Client) ListMessages 

func (c *Client) ListMessages(ctx context.Context, params ListMessagesParams) (*MessageList, error)

ListMessages returns one page of message history.

func (*Client) ListWebhooks 

func (c *Client) ListWebhooks(ctx context.Context) (Object, error)

func (*Client) Lookup 

func (c *Client) Lookup(ctx context.Context, number string) (*LookupResult, error)

Lookup answers whether a number has iMessage.

func (*Client) MarkConversationRead 

func (c *Client) MarkConversationRead(ctx context.Context, conversationHandle string) (Object, error)

func (*Client) RecheckContact 

func (c *Client) RecheckContact(ctx context.Context, number string) (Object, error)

RecheckContact re-runs the iMessage/SMS service check right now.

func (*Client) ReplaceWebhooks 

func (c *Client) ReplaceWebhooks(ctx context.Context, webhooks []WebhookParams) (Object, error)

ReplaceWebhooks swaps the whole webhook set in one call.

func (*Client) SendMessage 

func (c *Client) SendMessage(ctx context.Context, params SendMessageParams) (*OutboundMessage, error)

SendMessage queues a message; the result carries message_handle and status QUEUED.

func (*Client) SetCallForwarding 

func (c *Client) SetCallForwarding(ctx context.Context, lineHandle string, forwardingNumber *string) (Object, error)

SetCallForwarding queues a forwarding change for the operator (202); nil turns forwarding off.

func (*Client) SetOptOut 

func (c *Client) SetOptOut(ctx context.Context, number string, optedOut bool) (Object, error)

SetOptOut opts a number out of (or back into) all messaging.

func (*Client) UpdateContact 

func (c *Client) UpdateContact(ctx context.Context, number string, props Object) (Object, error)

func (*Client) UpdateLine 

func (c *Client) UpdateLine(ctx context.Context, lineHandle string, props Object) (Object, error)

UpdateLine changes a line's label / is_active by its line_handle. Pass a props map with "label" and/or "is_active".

func (*Client) UploadMedia 

func (c *Client) UploadMedia(ctx context.Context, path string) (string, error)

UploadMedia uploads a file (image/video/audio/PDF, max 50 MiB) and returns the public URL to pass as MediaURL in SendMessageParams.

func (*Client) UploadMediaReader 

func (c *Client) UploadMediaReader(ctx context.Context, r io.Reader, filename string) (string, error)

UploadMediaReader uploads media from any reader under the given filename.

type HistoryMessage 

type HistoryMessage struct {
	MessageHandle      string `json:"message_handle"`
	Number             string `json:"number"`
	Content            string `json:"content"`
	MediaURL           string `json:"media_url"`
	Service            string `json:"service"`
	IsOutbound         bool   `json:"is_outbound"`
	Status             string `json:"status"` // DELIVERED | SENT | RECEIVED
	DateSent           string `json:"date_sent"`
	ConversationHandle string `json:"conversation_handle"`
}

HistoryMessage is one row of the message history (both directions).

type ListMessagesParams 

type ListMessagesParams struct {
	Number             string
	Direction          string // "in" | "out"
	LineHandle         string
	ConversationHandle string
	Service            string
	Since              string
	Until              string
	Limit              int
	Before             string
}

ListMessagesParams filters the message history. Before is the cursor: pass NextBefore from the previous page.

type LookupResult 

type LookupResult struct {
	Number    string `json:"number"`
	Service   string `json:"service"` // iMessage | SMS
	Cached    bool   `json:"cached"`
	CheckedAt string `json:"checked_at"`
}

LookupResult answers "does this number have iMessage?".

type MessageList 

type MessageList struct {
	Messages   []HistoryMessage `json:"messages"`
	NextBefore string           `json:"next_before"`
}

MessageList is one page of history plus the cursor for the next one.

type Object 

type Object = map[string]any

Generic JSON object for endpoints whose shapes the SDK leaves untyped.

type Option 

type Option func(*Client)

Option customizes the Client.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (default DefaultBaseURL).

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client.

type OutboundMessage 

type OutboundMessage struct {
	Status        string          `json:"status"` // QUEUED | SENT | ERROR
	MessageHandle string          `json:"message_handle"`
	From          string          `json:"from"`
	To            json.RawMessage `json:"to"` // one number, or the participant list for group sends
	GroupID       string          `json:"group_id"`
	Content       string          `json:"content"`
	MediaURL      string          `json:"media_url"`
	Service       string          `json:"service"`
	ErrorMessage  string          `json:"error_message"`
	DateCreated   string          `json:"date_created"`
	DateUpdated   string          `json:"date_updated"`
	DateSent      string          `json:"date_sent"`
}

OutboundMessage is the public shape of a queued/sent message.

type SendMessageParams 

type SendMessageParams struct {
	Number         string `json:"number"`
	Content        string `json:"content,omitempty"`
	MediaURL       string `json:"media_url,omitempty"`       // from UploadMedia, or any public URL
	LineHandle     string `json:"line_handle,omitempty"`     // route via a specific line (see ListLines)
	StatusCallback string `json:"status_callback,omitempty"` // POSTed the final status
	ScheduledAt    string `json:"scheduled_at,omitempty"`    // ISO 8601 — deliver later
}

SendMessageParams describes one outbound message. Content is optional when MediaURL is set.

type WebhookParams 

type WebhookParams struct {
	URL    string   `json:"url"`
	Events []string `json:"events,omitempty"` // receive | outbound | line_blocked | line_unblocked
	Secret string   `json:"secret,omitempty"`
}

WebhookParams configures one webhook. Events defaults to every event; Secret enables the X-SMSBridge-Signature HMAC on deliveries.

Source Files

View all Source files

Directories

Path Synopsis
Smoke test for the Go SDK.
 Smoke test for the Go SDK.

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.