Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Go-SDK

E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Modul billionsend-go: jede API-Operation, Wiederholungsversuche und Idempotenzschlüssel.

Das Modul github.com/billionsend/billionsend-go ist der BillionSend-Client für Go. Es deckt jede Operation der API-Referenz ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Seine Typen stammen aus dem OpenAPI-Dokument der API. Der Quellcode liegt auf GitHub unter billionsend/billionsend-go.

Installation

Erfordert Go 1.23 oder neuer. Das Modul nutzt nur die Standardbibliothek.

go get github.com/billionsend/billionsend-go

E-Mail senden

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	ctx := context.Background()
	client := billionsend.NewClient() // liest BILLIONSEND_API_KEY

	sent, err := client.Emails.Send(ctx, &billionsend.SendEmailRequest{
		From:    "Acme <hello@acme.dev>",
		To:      []string{"success@simulator.amazonses.com"},
		Subject: "Welcome to Acme",
		HTML:    billionsend.String("<p>Glad you are here.</p>"),
	}, billionsend.WithIdempotencyKey("welcome/ana"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(sent.ID)
}

billionsend.NewClient(billionsend.WithAPIKey("bs_...")) nimmt den Schlüssel direkt entgegen. WithBaseURL, WithTimeout (pro Versuch, Standard 60 s), WithMaxRetries, WithHTTPClient und WithHeader legen den Rest fest. BILLIONSEND_BASE_URL überschreibt die API-URL.

Methodennamen

Jede Operation ist eine Methode, benannt nach ihrer ID in der API-Referenz, jedes durch Punkte getrennte Segment mit Großbuchstaben wie in Go: emails.send ist client.Emails.Send, emails.receiving.attachments.list ist client.Emails.Receiving.Attachments.List. emails.metrics ist client.Emails.Metrics.Get, neben Links, Countries und Clients.

Eine Methode nimmt den Kontext, die Pfadparameter der Reihe nach, den Request-Body (*XxxRequest), die Query- und Header-Parameter (*XxxParams) und danach Optionen. Optionale Felder sind Zeiger, erzeugt mit billionsend.String, Int64, Float64 und Bool. Ein Feld, das mehr als eine Form annimmt, etwa eine Adresse oder eine Liste davon, hat den Typ any.

Idempotenz und Wiederholungsversuche

Die acht Versand-Operationen (Emails.Send, Emails.Batch, Antworten und Weiterleitungen auf empfangene Mails, Inboxes.Send, Inboxes.Drafts.Send, Thread-Antworten und -Weiterleitungen) senden immer einen Idempotency-Key. Ohne WithIdempotencyKey denkt sich jeder Aufruf einen aus, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.

Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler und das 409 concurrent_idempotent_requests, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: GET, PUT, DELETE und die Versand-Operationen. Der Client wartet so lange, wie Retry-After es verlangt, bis zu einer Minute, und weicht sonst exponentiell von 500 ms bis 8 s zurück. WithRequestTimeout, WithRequestMaxRetries, WithRequestHeader und WithResponseHeaders wirken pro Aufruf.

Fehler

Ein fehlgeschlagener Aufruf liefert *ValidationError (400, 422), *AuthenticationError (401 oder kein Schlüssel konfiguriert), *PermissionDeniedError (403), *NotFoundError (404), *ConflictError (409), *RateLimitError (429, mit RetryAfter), *APIError (5xx), *APIConnectionError (keine Antwort) oder *APITimeoutError (der Versuch hat das Zeitlimit überschritten). Jeder lässt sich zu *billionsend.Error entpacken, mit StatusCode, Name (dem Fehlernamen der API), Message und RequestID, dem x-request-id der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.

_, err := client.Emails.Get(ctx, id)
var notFound *billionsend.NotFoundError
var apiErr *billionsend.Error
switch {
case errors.As(err, &notFound):
	// no such email
case errors.As(err, &apiErr):
	log.Printf("%d %s: %s (request %s)", apiErr.StatusCode, apiErr.Name, apiErr.Message, apiErr.RequestID)
}

Listen

Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem einen ...All-Iterator, der die nächsten Seiten nach und nach abruft, rückwärts, wenn Before gesetzt ist:

for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
	if err != nil {
		return err
	}
	fmt.Println(contact.Email)
}

Das Postfach eines Agenten

Warten Sie im Ereignis-Stream auf neue Mails und antworten Sie in ihrem Thread:

stream, err := client.Inboxes.Events.StreamInbox(ctx, "support@acme.dev", &billionsend.InboxesEventsStreamInboxParams{
	Types: billionsend.String("inbox.email.received"),
})
if err != nil {
	return err
}
defer stream.Close()

for item, err := range stream.Events() {
	if err != nil {
		return err // reconnecting ran out, or the key stopped working
	}
	ev, ok := item.(*billionsend.InboxStreamEvent)
	if !ok {
		continue // a *StreamGapEvent: events may be missing, read the threads again
	}
	d := ev.Data.Data
	_, err := client.Inboxes.Threads.Emails.Reply(ctx, ev.Data.InboxID, d.ThreadID, d.EmailID,
		&billionsend.InboxReplyRequest{Text: billionsend.String("Thanks, we are on it.")},
		billionsend.WithIdempotencyKey("reply/"+d.EmailID),
	)
	if err != nil {
		return err
	}
}

Der Stream verbindet sich mit Last-Event-ID neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie stream.LastEventID() und übergeben Sie es mit WithLastEventID zurück, um nach einem Neustart fortzusetzen. Ein *StreamGapEvent kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. WithMaxReconnects (Standard 5), WithReconnectDelay und WithoutReconnect steuern das Wiederverbinden. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. client.Inboxes.Events.Stream folgt jedem Postfach, das der Schlüssel lesen kann.

Webhooks verifizieren

VerifyWebhook prüft Signatur und Zeitstempel einer Webhook-Zustellung mit dem whsec_-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist:

http.HandleFunc("/webhooks/billionsend", func(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	event, err := billionsend.VerifyWebhook(body, r.Header, os.Getenv("BILLIONSEND_WEBHOOK_SECRET"))
	if err != nil {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}
	log.Print(event.Type)
	w.WriteHeader(http.StatusNoContent)
})

Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt, und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.

Agent-Registrierung

signup, err := billionsend.NewClient().Agent.Signup(ctx, &billionsend.AgentSignupRequest{
	HumanEmail: "owner@acme.dev",
	Name:       "Support agent",
})
if err != nil {
	return err
}
fmt.Println(signup.Inbox.EmailAddress)

Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter Agent-Registrierung.

War diese Seite hilfreich?