Go · Gin

Send your first email from a Gin application in three steps: install the SDK, add a route that sends, and run it.

1. Install

代码示例

go mod init example.com/bird-gin-quickstart
go get github.com/gin-gonic/gin github.com/messagebird/bird-sdk-go

The SDK requires Go 1.24+. Grab an API key from Developers > API keys in the dashboard and export it; the SDK infers the region from the key's bk_us1_ / bk_eu1_ prefix, so nothing else needs configuring:

代码示例

export BIRD_API_KEY="bk_us1_..."

2. Send

Create main.go with a route that sends through Bird's shared onboarding domain, so no domain verification is needed:

代码示例

package main

import (
	"errors"
	"log"
	"net/http"
	"os"

	"github.com/gin-gonic/gin"
	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}

	r := gin.Default()
	r.POST("/send", func(c *gin.Context) {
		msg, err := client.Email.Send(c.Request.Context(), bird.EmailSendParams{
			From:    "onboarding@messagebird.dev",
			To:      []string{"delivered@messagebird.dev"},
			Subject: "Hello from Bird",
			HTML:    "<p>My first Bird email.</p>",
		})
		if err != nil {
			var apiErr *bird.APIError
			if errors.As(err, &apiErr) {
				c.JSON(apiErr.StatusCode, gin.H{"error": apiErr.Error()})
				return
			}
			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
			return
		}
		c.JSON(http.StatusAccepted, msg)
	})

	log.Fatal(r.Run(":3000"))
}

The SDK generates one idempotency key per Send call and reuses it when retrying timeouts, 429 responses, and 5xx responses. A retry therefore does not create a second send.

3. Try it

代码示例

go run . &
curl -X POST localhost:3000/send

Bird responds with 202, accepting the email for asynchronous delivery, and the route returns the message. The *_count fields track recipients through the delivery states. In the initial response, one recipient is accepted and none are delivered:

代码示例

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

Because the recipient is the delivered@messagebird.dev sandbox address, delivery is guaranteed. Fetch the message by its em_ ID with client.Email.Get and watch the status move to delivered.

Next steps

Go SDK reference: every method, param, and error type.
Send your first email: the same flow with curl and the dashboard.
Sending domains: verify your own domain for production sending.
Email API reference: the full request and response schema.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideTesting email without spamming anyone Explore the capabilityTest email delivery Follow the learning pathOperate messaging reliably

Try the practice and get an implementation brief