Saltar al contenido principal
SDKs · Go

SDK Go

Go 1.24+, context en cada llamada e iteradores para paginar.

v0.1.0pkg.go.devGitHub70 métodos(*T, error)

Instalación

Agrega el paquete al proyecto.

terminal
go get github.com/Coffee-Mail/coffee-mail-sdk-go

Configurar el cliente

La clave viene de COFFEEMAIL_API_KEY o del constructor. Usa una clave por entorno.

cliente
import coffeemail "github.com/Coffee-Mail/coffee-mail-sdk-go" client, err := coffeemail.NewClient("") // vazio: lê COFFEEMAIL_API_KEYif err != nil {	log.Fatal(err)}

Enviar un email

El envío entra en la cola y vuelve en milisegundos con el id y el estado queued. Retorno: (*T, error).

Los métodos devuelven (*T, error), en el idioma de Go: revisa err antes de usar el valor. Los errores de la API son *coffeemail.Error y funcionan con errors.Is (ErrNotFound, ErrRateLimited…).
enviar
sent, err := client.Emails.Send(ctx, &coffeemail.SendEmailParams{	From:    coffeemail.Address{Email: "pedidos@acme.com.br", Name: "Acme"},	To:      []coffeemail.Address{{Email: "ana@exemplo.com.br"}},	Subject: "Seu pedido #4821 foi enviado",	HTML:    "<p>Chega amanhã.</p>",})if err != nil {	return err}log.Println(sent.ID, sent.Status)

Manejar errores

Los errores de la API llegan tipados, con code, status y requestId; nada se lanza en el camino común.

errores
_, err := client.Domains.Get(ctx, id)if errors.Is(err, coffeemail.ErrNotFound) {	return nil} var apiErr *coffeemail.Errorif errors.As(err, &apiErr) {	log.Printf("status=%d code=%s requestId=%s", apiErr.Status, apiErr.Code, apiErr.RequestID)}

Paginar

Las listas devuelven la página y el cursor nextCursor; pásalo en after para traer la siguiente.

paginar
for email, err := range client.Emails.ListAll(ctx, &coffeemail.ListEmailsParams{}) {	if err != nil {		return err	}	handle(email)}

Verificar webhooks

Valida x-webhook-signature con el cuerpo bruto de la solicitud, x-webhook-timestamp y x-webhook-idempotency-key. La ventana por defecto es de 300 segundos.

El subpaquete webhook verifica la firma. Para revisar a mano: sha256= + HMAC-SHA256, en hex, de "timestamp.idempotencyKey.cuerpo" con el secreto whsec_, comparado en tiempo constante.
webhook
import "github.com/Coffee-Mail/coffee-mail-sdk-go/webhook" event, err := webhook.ParseRequest(r, os.Getenv("COFFEEMAIL_WEBHOOK_SECRET"))if err != nil {	http.Error(w, "assinatura inválida", http.StatusUnauthorized)	return}

Referencia de métodos

Todos los métodos públicos, agrupados por recurso. Cada fila muestra el endpoint llamado; abre la referencia de la API para ver campos y respuestas.

Emails8 métodos

Endpoints →
MétodoEndpoint llamado
client.Emails.Send(ctx, …)POST/emails
client.Emails.SendBatch(ctx, …)POST/emails/batch
client.Emails.Get(ctx, …)GET/emails/{id}
client.Emails.List(ctx, …)GET/emails
client.Emails.GetEvents(ctx, …)GET/emails/{id}/events
client.Emails.GetTags(ctx, …)GET/emails/tags
client.Emails.Cancel(ctx, …)POST/emails/{id}/cancel
client.Emails.Resend(ctx, …)POST/emails/{id}/resend

Dominios10 métodos

Endpoints →
MétodoEndpoint llamado
client.Domains.Create(ctx, …)POST/domains
client.Domains.List(ctx, …)GET/domains
client.Domains.Get(ctx, …)GET/domains/{id}
client.Domains.Verify(ctx, …)POST/domains/{id}/verify
client.Domains.Delete(ctx, …)DELETE/domains/{id}
client.Domains.GetHealth(ctx, …)POST/domains/{id}/health
client.Domains.GetWarmupStatus(ctx, …)GET/domains/{id}/warmup
client.Domains.RotateDKIM(ctx, …)POST/domains/{id}/dkim/rotate
client.Domains.SetTrackingDomain(ctx, …)PUT/domains/{id}/tracking-domain
client.Domains.RemoveTrackingDomain(ctx, …)DELETE/domains/{id}/tracking-domain

Plantillas12 métodos

Endpoints →
MétodoEndpoint llamado
client.Templates.Create(ctx, …)POST/templates
client.Templates.List(ctx, …)GET/templates
client.Templates.Get(ctx, …)GET/templates/{id}
client.Templates.Update(ctx, …)PATCH/templates/{id}
client.Templates.Delete(ctx, …)DELETE/templates/{id}
client.Templates.Preview(ctx, …)POST/templates/preview
client.Templates.Format(ctx, …)POST/templates/format
client.Templates.TestRender(ctx, …)POST/templates/test-render
client.Templates.TestSend(ctx, …)POST/templates/{id}/test-send
client.Templates.ListVersions(ctx, …)GET/templates/{id}/versions
client.Templates.GetVersion(ctx, …)GET/templates/{id}/versions/{version}
client.Templates.RestoreVersion(ctx, …)POST/templates/{id}/versions/{version}/restore

Audiencias y contactos10 métodos

Endpoints →
MétodoEndpoint llamado
client.Audiences.Create(ctx, …)POST/audiences
client.Audiences.List(ctx, …)GET/audiences
client.Audiences.Get(ctx, …)GET/audiences/{id}
client.Audiences.Update(ctx, …)PUT/audiences/{id}
client.Audiences.Delete(ctx, …)DELETE/audiences/{id}
client.Audiences.Contacts.Create(ctx, …)POST/audiences/{id}/contacts
client.Audiences.Contacts.List(ctx, …)GET/audiences/{id}/contacts
client.Audiences.Contacts.BulkAdd(ctx, …)POST/audiences/{id}/contacts/bulk
client.Audiences.Contacts.Update(ctx, …)PUT/audiences/{id}/contacts/{contactId}
client.Audiences.Contacts.Delete(ctx, …)DELETE/audiences/{id}/contacts/{contactId}

Campañas6 métodos

Endpoints →
MétodoEndpoint llamado
client.Broadcasts.Create(ctx, …)POST/broadcasts
client.Broadcasts.List(ctx, …)GET/broadcasts
client.Broadcasts.Get(ctx, …)GET/broadcasts/{id}
client.Broadcasts.Send(ctx, …)POST/broadcasts/{id}/send
client.Broadcasts.TestSend(ctx, …)POST/broadcasts/{id}/test-send
client.Broadcasts.Cancel(ctx, …)POST/broadcasts/{id}/cancel

Remitentes5 métodos

Endpoints →
MétodoEndpoint llamado
client.Senders.Create(ctx, …)POST/senders
client.Senders.List(ctx, …)GET/senders
client.Senders.Verify(ctx, …)POST/senders/verify
client.Senders.ResendVerification(ctx, …)POST/senders/{id}/resend-verification
client.Senders.Delete(ctx, …)DELETE/senders/{id}

Supresiones6 métodos

Endpoints →
MétodoEndpoint llamado
client.Suppressions.Create(ctx, …)POST/suppressions
client.Suppressions.List(ctx, …)GET/suppressions
client.Suppressions.Get(ctx, …)GET/suppressions/{id}
client.Suppressions.Delete(ctx, …)DELETE/suppressions/{id}
client.Suppressions.Reactivate(ctx, …)POST/suppressions/{id}/reactivate
client.Suppressions.BulkCreate(ctx, …)POST/suppressions/bulk

Webhooks11 métodos

Endpoints →
MétodoEndpoint llamado
client.Webhooks.Create(ctx, …)POST/webhooks
client.Webhooks.List(ctx, …)GET/webhooks
client.Webhooks.Get(ctx, …)GET/webhooks/{id}
client.Webhooks.Update(ctx, …)PUT/webhooks/{id}
client.Webhooks.Toggle(ctx, …)PATCH/webhooks/{id}
client.Webhooks.Delete(ctx, …)DELETE/webhooks/{id}
client.Webhooks.RotateSecret(ctx, …)POST/webhooks/{id}/rotate-secret
client.Webhooks.ListDeliveries(ctx, …)GET/webhooks/{id}/deliveries
client.Webhooks.Test(ctx, …)POST/webhooks/{id}/test
client.Webhooks.GetDelivery(ctx, …)GET/webhooks/{id}/deliveries/{deliveryId}
client.Webhooks.ReplayDelivery(ctx, …)POST/webhooks/{id}/deliveries/{deliveryId}/replay

Estadísticas1 método

Endpoints →
MétodoEndpoint llamado
client.Stats.Get(ctx, …)GET/stats

Validación1 método

Endpoints →
MétodoEndpoint llamado
client.Validation.Validate(ctx, …)POST/validate