iris

package module
v0.1.1 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

Go Reference Tests Release MIT License

Website · API reference · Go docs


Send receipts, codes and notifications from your Go server in a few lines, with 221 Pay (Wave, Orange Money) payment links built in. One dependency, the official Standard Webhooks library, for verifying webhooks.

Install

go get github.com/orvlabs/iris-go

Create a key in the Iris console under API keys. Keep it on your server, never in a browser or mobile app.

Send an email

package main

import (
	"context"
	"log"
	"os"

	iris "github.com/orvlabs/iris-go"
)

func main() {
	client := iris.New(os.Getenv("IRIS_API_KEY"))

	sent, err := client.SendEmail(context.Background(), 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"},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("queued", sent.MessageID)
}

[!TIP] Use a test key (iris_test_…) while you build. It is checked exactly like a real one, but nothing is delivered and no units are used.

Ask for a payment

sent, err := client.SendEmail(ctx, iris.Email{
	Sender:      iris.Address{Email: "factures@boutique.sn"},
	To:          []iris.Address{{Email: "awa@example.sn"}},
	Subject:     "Votre facture",
	HTMLContent: "<p>Votre facture est prête.</p>{{bloc_paiement}}",
	Payment: &iris.Payment{
		AmountXOF:   15000,
		Reference:   "FAC-2026-0042",
		Description: "Facture FAC-2026-0042",
		Methods:     []string{"wave", "orange_money"},
	},
})

The same reference and amount always reuse the same link. Link your 221 Pay merchant account in the console first.

Handle errors

Every error from the API is an *iris.Error with the HTTP status and a stable Code.

var apiErr *iris.Error
if errors.As(err, &apiErr) {
	switch {
	case apiErr.Code == "not_enough_credits":
		// top up in the console
	case apiErr.Retryable(): // 429, 502, 503
		// retry later, with an increasing delay
	default:
		log.Printf("iris refused: %s (%s)", apiErr.Code, apiErr.Message)
	}
}

[!WARNING] Sending has no idempotency key: retrying after a network timeout can send the email twice.

Verify a webhook

http.HandleFunc("/webhooks/iris", func(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "unreadable body", http.StatusBadRequest)
		return
	}
	ev, err := iris.VerifyWebhook(os.Getenv("IRIS_WEBHOOK_SECRET"), r.Header, body) // whsec_…
	if err != nil {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	// Deduplicate on ev.ID: a retry carries the same one.
	log.Println(ev.Type, ev.Data.Email) // email.delivered, email.bounced, email.opened…
	w.WriteHeader(http.StatusNoContent)
})

Read the raw body before parsing it: the signature covers the exact bytes.

What's in the box

iris.New(key) Client for https://iris.orvlabs.com, 30 s timeout. Swap BaseURL or HTTPClient if you need to.
client.SendEmail(ctx, email) Send now, or later with ScheduledAt. Templates, attachments, one-click unsubscribe, 221 Pay links.
*iris.Error Status, Code, Message, Retryable().
iris.VerifyWebhook(secret, headers, body) Checks the signature and decodes the email event.

Every route, field and error code is in the API reference.

License

MIT, by Orvene.

Documentation

Overview

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

Index

Examples

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.

Example
package main

import (
	"context"
	"fmt"

	iris "github.com/orvlabs/iris-go"
)

func main() {
	client := iris.New("iris_test_xxxxxxxx")
	_, err := client.SendEmail(context.Background(), iris.Email{
		Sender:      iris.Address{Email: "factures@boutique.sn"},
		To:          []iris.Address{{Email: "awa@example.sn"}},
		Subject:     "Votre facture",
		HTMLContent: "<p>Votre facture est prête.</p>{{bloc_paiement}}",
		Payment: &iris.Payment{
			AmountXOF:   15000,
			Reference:   "FAC-2026-0042",
			Description: "Facture FAC-2026-0042",
			Methods:     []string{"wave", "orange_money"},
		},
	})
	fmt.Println(err != nil)
}

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