iris

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 8 Imported by: 0

README

iris-go

Go client for Iris, transactional email for Senegal.

go get github.com/orvlabs/iris-go

Send an email

client := iris.New(os.Getenv("IRIS_API_KEY")) // iris_… or iris_test_…

sent, err := client.SendEmail(ctx, iris.Email{
	Sender:      iris.Address{Email: "commandes@boutique.sn", Name: "Boutique"},
	To:          []iris.Address{{Email: "awa@example.sn", Name: "Awa"}},
	Subject:     "Votre commande",
	HTMLContent: "<p>Merci {{params.prenom}} !</p>",
	Params:      map[string]any{"prenom": "Awa"},
})
var apiErr *iris.Error
if errors.As(err, &apiErr) {
	// apiErr.Status, apiErr.Code (not_enough_credits, key_scope…), apiErr.Retryable()
}

Keep the key on your server. A test key (iris_test_…) is validated like a real one but delivers nothing and uses no units.

Verify a webhook

func handler(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	ev, err := iris.VerifyWebhook(os.Getenv("IRIS_WEBHOOK_SECRET"), r.Header, body) // whsec_…
	if err != nil {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	// ev.ID (deduplicate on it), ev.Type (email.delivered, email.bounced…), ev.Data.Email
	w.WriteHeader(http.StatusNoContent)
}

Every route, field and error code: API reference.

License

MIT

Documentation

Overview

Package iris sends transactional email through Iris (https://iris.orvlabs.com) and verifies its webhooks.

Index

Constants

View Source
const DefaultBaseURL = "https://iris.orvlabs.com"

Variables

This section is empty.

Functions

This section is empty.

Types

type Address

type Address struct {
	Email string `json:"email"`
	Name  string `json:"name,omitempty"`
}

type Attachment

type Attachment struct {
	Name    string `json:"name"`
	Content string `json:"content"`
}

Attachment content is base64; Iris accepts 10 MB decoded at most in total.

type Client

type Client struct {
	Key        string
	BaseURL    string
	HTTPClient *http.Client
}

Client calls the Iris API with one key. Use it from your server only: the key must stay secret.

func New

func New(key string) *Client

New returns a client for key (iris_… or iris_test_…).

func (*Client) SendEmail

func (c *Client) SendEmail(ctx context.Context, email Email) (*Sent, error)

SendEmail queues an email. It has no idempotency key: retrying after a network timeout can send it twice.

type Email

type Email struct {
	Sender      Address           `json:"sender"`
	To          []Address         `json:"to,omitempty"`
	Cc          []Address         `json:"cc,omitempty"`
	Bcc         []Address         `json:"bcc,omitempty"`
	ReplyTo     *Address          `json:"replyTo,omitempty"`
	Subject     string            `json:"subject,omitempty"`
	HTMLContent string            `json:"htmlContent,omitempty"`
	TextContent string            `json:"textContent,omitempty"`
	TemplateID  int64             `json:"templateId,omitempty"`
	Params      map[string]any    `json:"params,omitempty"`
	Headers     map[string]string `json:"headers,omitempty"`
	Attachment  []Attachment      `json:"attachment,omitempty"`
	ScheduledAt *time.Time        `json:"scheduledAt,omitempty"`
	BatchID     string            `json:"batchId,omitempty"`
	Payment     *Payment          `json:"payment,omitempty"`
	Unsubscribe bool              `json:"unsubscribe,omitempty"`
}

type Error

type Error struct {
	Status  int    `json:"-"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

Error is an answer other than 2xx. Branch on Status and Code; Message is French text that may change.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Retryable

func (e *Error) Retryable() bool

Retryable reports a temporary failure (429, 502, 503): retry with an increasing delay.

type Event

type Event struct {
	ID        string    `json:"id"`
	Type      string    `json:"type"`
	CreatedAt time.Time `json:"createdAt"`
	Data      struct {
		MessageID string `json:"messageId"`
		Email     string `json:"email"`
		URL       string `json:"url"`
	} `json:"data"`
}

Event is an email event webhook. Deduplicate on ID: retries carry the same one.

func VerifyWebhook

func VerifyWebhook(secret string, headers http.Header, body []byte) (*Event, error)

VerifyWebhook checks the Standard Webhooks signature of a delivery with your whsec_ secret, then decodes it. Pass the raw body, before any parsing, and the request headers.

type Payment

type Payment struct {
	AmountXOF   int64    `json:"amountXof"`
	Reference   string   `json:"reference"`
	Description string   `json:"description"`
	ExpiresIn   int      `json:"expiresIn,omitempty"`
	Methods     []string `json:"methods,omitempty"`
}

Payment adds a 221 Pay link (Wave, Orange Money) of your linked merchant account. Amounts are whole CFA francs.

type Sent

type Sent struct {
	MessageID  string   `json:"messageId"`
	MessageIDs []string `json:"messageIds"`
	BatchID    string   `json:"batchId"`
}

Sent is the answer to SendEmail. BatchID is set only for a scheduled email.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL