Přejít na obsah
Dokumentace

Tutoriál

Odesílání e-mailů z Go

Odesílejte e-maily z Go přes SDK emailit-go nebo net/smtp, ošetřete chyby API a ověřujte podpisy webhooků Emailitu v handleru net/http.

Aktualizováno 1. 10. 2026

Tento návod ukazuje, jak odesílat e-maily ze služby v Go přes oficiální SDK emailit-go, jak místo toho použít net/smtp a jak ověřovat webhooky v handleru net/http.

Předpoklady

Nainstalujte SDK

Terminal
go get github.com/emailit/emailit-go/v2

SDK závisí jen na standardní knihovně Go.

Nastavte API klíč

Předejte klíč svému procesu jako proměnnou prostředí:

Terminal
export EMAILIT_API_KEY=secret_••••••••••••••••••••••••••••••••

Odešlete e-mail

main.go
package main

import (
	"log"
	"os"

	"github.com/emailit/emailit-go/v2"
)

func main() {
	client := emailit.NewClient(os.Getenv("EMAILIT_API_KEY"))

	email, err := client.Emails.Send(&emailit.SendEmailRequest{
		From:    "Acme <hello@acme.com>",
		To:      []string{"ada@example.com"},
		Subject: "Your login code",
		Text:    "Your code is 482913. It expires in 10 minutes.",
		Html:    "<p>Your code is <strong>482913</strong>. It expires in 10 minutes.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Println("sent", email.Id) // em_…
}

Klienta vytvořte jednou a sdílejte ho; mezi požadavky ho lze bezpečně používat opakovaně. Pokud chcete odeslat uloženou šablonu, nastavte Template na její alias nebo ID tem_ a předejte Variables. Pokud chcete změnit časové limity, předejte vlastního klienta: emailit.NewClient(key, emailit.WithHTTPClient(&http.Client{Timeout: 10 * time.Second})).

Ošetřete chyby

SDK vrací běžné chyby Go a pomocné funkce k jejich rozlišení:

Go
email, err := client.Emails.Send(req)
if err != nil {
	switch {
	case emailit.IsRateLimitError(err):
		// 429: back off and retry
	case emailit.IsAuthenticationError(err):
		// 401: the API key is missing or invalid
	case emailit.IsUnprocessableEntityError(err):
		// 422: for example, the from domain isn't verified
	}

	var apiErr *emailit.APIError
	if errors.As(err, &apiErr) {
		log.Printf("emailit: %d %s", apiErr.StatusCode, apiErr.Message)
	}
	return err
}

Odesílání přes SMTP

Balíček net/smtp ze standardní knihovny umí odesílat přes SMTP relay Emailitu. smtp.SendMail před autentizací přepne spojení na šifrované příkazem STARTTLS:

smtp.go
package main

import (
	"log"
	"net/smtp"
	"os"
	"strings"
)

func main() {
	auth := smtp.PlainAuth("", "emailit", os.Getenv("EMAILIT_API_KEY"), "smtp.emailit.com")

	msg := strings.Join([]string{
		"From: Acme <hello@acme.com>",
		"To: ada@example.com",
		"Subject: Your login code",
		"MIME-Version: 1.0",
		"Content-Type: text/plain; charset=UTF-8",
		"",
		"Your code is 482913. It expires in 10 minutes.",
	}, "\r\n")

	err := smtp.SendMail("smtp.emailit.com:587", auth, "hello@acme.com", []string{"ada@example.com"}, []byte(msg))
	if err != nil {
		log.Fatal(err)
	}
}

net/smtp je minimalistický: zprávu sestavujete sami a nepodporuje implicitní TLS na portu 465. Pro HTML, přílohy nebo opakované použití spojení použijte udržovanou e-mailovou knihovnu, nebo API. Pokud je port 587 blokovaný, použijte smtp.emailit.com:2525. Viz Nastavení SMTP.

Přijímejte webhooky

Vytvořte webhook a jeho tajný klíč uložte do EMAILIT_WEBHOOK_SECRET. Handler přečte surové tělo požadavku, zkontroluje podpis a pak dekóduje pole událostí:

webhooks.go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"
	"os"
	"strconv"
	"time"
)

type emailitEvent struct {
	EventID string `json:"event_id"`
	Type    string `json:"type"`
	Data    struct {
		Object map[string]any `json:"object"`
	} `json:"data"`
}

func validSignature(body []byte, signature, timestamp, secret string) bool {
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || signature == "" {
		return false
	}
	if age := time.Now().Unix() - ts; age > 300 || age < -300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

func emailitWebhook(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 10<<20))
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}

	if !validSignature(body, r.Header.Get("X-Emailit-Signature"), r.Header.Get("X-Emailit-Timestamp"), os.Getenv("EMAILIT_WEBHOOK_SECRET")) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}

	var events []emailitEvent // up to 100 events per request
	if err := json.Unmarshal(body, &events); err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}

	for _, event := range events {
		if event.Type == "email.bounced" {
			// Stop emailing event.Data.Object["to"].
		}
	}

	w.WriteHeader(http.StatusOK)
}

func main() {
	http.HandleFunc("POST /webhooks/emailit", emailitWebhook)
	http.ListenAndServe(":8080", nil)
}

Vzor POST /path vyžaduje Go 1.22 nebo novější; v Go 1.21 zaregistrujte /webhooks/emailit a r.Method kontrolujte sami. Do 30 sekund vraťte 2xx; při jiných odpovědích se požadavek opakuje. Viz Ověření podpisu webhooků.

Tipy pro produkční provoz

  • Držte se pod limitem rychlosti. Nové workspace mohou ve výchozím stavu odeslat 2 e-maily za sekundu a 5 000 za den. Hromadnou poštu odesílejte z workeru s omezovačem rychlosti, jako je golang.org/x/time/rate. Viz Limity a kvóty.
  • Zajistěte bezpečné opakování. Pokud po vypršení časového limitu požadavek opakujete, pošlete přes net/http hlavičku Idempotency-Key, aby se e-mail neodeslal dvakrát. Viz Idempotentní požadavky.
  • Odstraňujte duplicitní webhooky tak, že si uložíte každé zpracované EventID.
  • Nastavte časové limity. Použijte kontext nebo časový limit HTTP klienta, aby pomalá síť neblokovala gorutiny požadavků.

Další kroky

Přílohy, plánování a měření.
Hlavičky a jak zpomalit.
Všechny události a jejich obsah.
Všechny oficiální knihovny.

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.