Go SDK

go get github.com/mailafrica/go-sdk

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mailafrica/go-sdk"
)

func main() {
	ctx := context.Background()

	client := mailafrica.New(mailafrica.Config{
		BaseURL: "https://api.mailafrica.online",
		APIKey:  os.Getenv("MAIL_API_KEY"),
	})

	msg, err := client.SendEmail(ctx, mailafrica.SendEmailRequest{
		To:       []string{"recipient@example.com"},
		Subject:  "Hello from MailAfrica",
		HTMLBody: "<p>Hello!</p>",
		TextBody: "Hello!",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("sent message ID:", msg.ID)
}

client := mailafrica.New(mailafrica.Config{
	JWT: initialToken,
	TokenRefresher: func(ctx context.Context) (string, error) {
		return myRefreshLogic(ctx) // returns a fresh JWT
	},
})

// Register a new account (email or phone_number; password is required)
resp, err := client.Register(ctx, mailafrica.RegisterRequest{
	Email:       strPtr("user@example.com"),
	Phone:       strPtr("+255712345678"),
	Password:    "secure-password",
	Name:        "Jane Doe",
	CompanyName: "Acme Corp",
})
authToken    := resp.Token        // JWT access token
refreshToken := resp.RefreshToken // store it; the SDK never does

// Log in with an email or phone identifier
resp, err = client.Login(ctx, mailafrica.LoginRequest{
	Identifier: "user@example.com",
	Password:   "secure-password",
})

// Log in with a Google ID token
resp, err = client.GoogleLogin(ctx, "google-id-token")

// Exchange a refresh token for a fresh JWT
resp, err = client.Refresh(ctx, refreshToken)

// Fetch the current authenticated user
user, err := client.Me(ctx)

// Update your profile
user, err = client.UpdateMe(ctx, mailafrica.UpdateProfileRequest{
	Name:        strPtr("Jane D. Doe"),
	CompanyName: strPtr("Acme Inc"),
})

// Add or replace your email — sends a verification link
user, err := client.SetEmail(ctx, "new@example.com")

// Confirm the email using the token from the verification link
err = client.VerifyEmail(ctx, "verification-token")

// Re-send the verification email
err = client.ResendEmailVerification(ctx)

// Add or replace your phone — sends a 6-digit OTP
user, err = client.SetPhone(ctx, "+255712345678")

// Confirm the phone using the OTP
err = client.VerifyPhone(ctx, "123456")

// Re-send the OTP
err = client.ResendPhoneOTP(ctx)

// Create an inbound address
addr, err := client.CreateAddress(ctx, mailafrica.CreateAddressRequest{
	LocalPart: "hello",
	Label:     strPtr("Support inbox"),
})

// List all inbound addresses
addresses, err := client.ListAddresses(ctx)

// List messages with optional filters; returns pagination metadata
msgs, pagination, err := client.ListMessages(ctx, mailafrica.MessageListOpts{
	ListOpts:  mailafrica.ListOpts{Page: 1, PerPage: 25},
	AddressID: int64Ptr(addr.ID),
	Unread:    boolPtr(true),
})
fmt.Println("unread:", pagination.Total)

// Fetch one message by ID
msg, err := client.GetMessage(ctx, msgs[0].ID)

// Mark a message as read
err = client.MarkMessageRead(ctx, msg.ID)

// Delete an inbound address — it stops receiving mail
err = client.DeleteAddress(ctx, addr.ID)

// Add a receiving domain; returns the DNS records to publish
dom, err := client.CreateInboundDomain(ctx, "inbound.example.com")
fmt.Println(dom.VerificationRecord.Type, dom.VerificationRecord.Host, dom.VerificationRecord.Value)

// List receiving domains
domains, err := client.ListInboundDomains(ctx)

// Verify once DNS propagates
err = client.VerifyInboundDomain(ctx, dom.ID)

// Delete a receiving domain
err = client.DeleteInboundDomain(ctx, dom.ID)

// Send a single email
msg, err := client.SendEmail(ctx, mailafrica.SendEmailRequest{
	To:       []string{"customer@example.com"},
	Cc:       []string{"billing@example.com"},
	Subject:  "Your receipt",
	HTMLBody: "<p>Thanks for your order #482.</p>",
	TextBody: "Thanks for your order #482.",
	// Send from your own verified sending domain:
	FromDomainID: int64Ptr(7),
	FromAddress:  strPtr("hello@example.com"),
})

// Send to many recipients in one call
result, err := client.BatchSend(ctx, mailafrica.BatchSendRequest{
	To:       []string{"a@example.com", "b@example.com"},
	Subject:  "Batch update",
	HTMLBody: "<p>Hello!</p>",
	TextBody: "Hello!",
})
fmt.Println("sent:", result.Sent, "of", result.Total)

// List sent emails (paginated)
emails, pagination, err := client.ListSentEmails(ctx, mailafrica.ListOpts{
	Page:    1,
	PerPage: 25,
})

// Fetch a sent email with per-recipient delivery statuses
detail, err := client.GetSentEmail(ctx, emails[0].ID)
for _, r := range detail.Recipients {
	fmt.Println(r.Recipient, r.Status)
}

// Create a template with {{variable}} placeholders
tpl, err := client.CreateTemplate(ctx, mailafrica.TemplateRequest{
	Name:     "Welcome",
	Subject:  "Welcome {{name}}!",
	HTMLBody: "<p>Hi {{name}},</p>",
	TextBody: "Hi {{name}},",
})

// List / get / update / delete templates
tpls, err := client.ListTemplates(ctx)
tpl, err = client.GetTemplate(ctx, tpl.ID)
tpl, err = client.UpdateTemplate(ctx, tpl.ID, mailafrica.TemplateRequest{
	Name:     "Welcome v2",
	Subject:  "Welcome!",
	HTMLBody: "<p>Welcome!</p>",
})
err = client.DeleteTemplate(ctx, tpl.ID)

// Send with a template plus variables
msg, err := client.SendEmail(ctx, mailafrica.SendEmailRequest{
	To:         []string{"customer@example.com"},
	TemplateID: int64Ptr(tpl.ID),
	Variables:  map[string]string{"name": "Jane"},
})

// Add a sending domain; DNSRecords carries what to publish
resp, err := client.AddSendingDomain(ctx, mailafrica.AddSendingDomainRequest{
	Domain:        "example.com",
	FromLocalPart: "hello",
})
fmt.Println("DKIM host:", resp.DNSRecords.DKIM.Host)
fmt.Println("DKIM TXT:",  resp.DNSRecords.DKIM.Value)

// List sending domains
domains, err := client.ListSendingDomains(ctx)

// Verify a domain once DNS propagates
err = client.VerifySendingDomain(ctx, resp.Domain.ID)

// Delete a sending domain
err = client.DeleteSendingDomain(ctx, resp.Domain.ID)

// Create a sender address on a domain (e.g. hello@example.com)
addr, err := client.CreateSenderAddress(ctx, domainID, "hello")

// List sender addresses
addrs, err := client.ListSenderAddresses(ctx)

// Delete a sender address
err = client.DeleteSenderAddress(ctx, addr.ID)

// Create a webhook; Secret is auto-generated if omitted
wh, err := client.CreateWebhook(ctx, mailafrica.CreateWebhookRequest{
	AddressID: addr.ID,
	URL:       "https://example.com/hooks/inbound",
	Secret:    "whsec_...",
})
// wh.Secret is returned only on creation — store it securely

// List webhooks for an address
webhooks, err := client.ListWebhooks(ctx, addr.ID)

// Inspect delivery attempts (status, retries, last_error)
deliveries, err := client.ListWebhookDeliveries(ctx, wh.ID)

// Send a test ping
err = client.TestWebhook(ctx, wh.ID)

// Manually trigger the webhook
err = client.TriggerWebhook(ctx, wh.ID)

// Delete a webhook
err = client.DeleteWebhook(ctx, wh.ID)

// Create a sandbox OAuth credential with scopes
cred, err := client.CreateSandboxCredential(ctx, mailafrica.CreateCredentialRequest{
	Scopes: strPtr("send,read"),
})

// List sandbox credentials
creds, err := client.ListSandboxCredentials(ctx)

// Revoke a credential
err = client.RevokeSandboxCredential(ctx, cred.ID)

// SMTP credentials for sending test mail into the sandbox
smtp, err := client.GetSMTPSandboxCredentials(ctx)
// smtp.Password is shown only on first generation / regeneration

// Regenerate the SMTP password
smtp, err = client.RegenerateSMTPSandboxPassword(ctx)

// Read sandbox mail (paginated)
messages, pagination, err := client.ListSandboxMessages(ctx, mailafrica.ListOpts{PerPage: 25})

// Fetch one sandbox message
smsg, err := client.GetSandboxMessage(ctx, messages[0].ID)

// Wipe the sandbox inbox
err = client.ClearSandboxMessages(ctx)

// Read the wallet balance
balance, err := client.GetBalance(ctx)
fmt.Println("balance (TZS):", balance.BalanceTZS)

// Start a card / other top-up
topup, err := client.InitiateTopup(ctx, 10000)

// Start a mobile-money (phone) top-up
topup, err = client.InitiatePhoneTopup(ctx, 10000)
// topup.CheckoutURL / topup.PaymentLinkURL / topup.ProviderReference guide the payment

// Create a notification rule
notif, err := client.CreateSMSNotification(ctx, mailafrica.CreateSMSNotificationRequest{
	AddressID:   addr.ID,
	PhoneNumber: "+255712345678",
	APIKey:      "SENDAFRICA_...",
})
// notif.APIKey is shown only once — store it securely

// List notification rules for an address
notifs, err := client.ListSMSNotifications(ctx, addr.ID)

// Inspect delivery attempts
deliveries, err := client.ListSMSDeliveries(ctx, notif.ID)

// Revoke a notification rule
err = client.RevokeSMSNotification(ctx, notif.ID)

// Get the compliance profile
profile, err := client.GetComplianceProfile(ctx)

// Update PDPC registration, retention, etc.
profile, err = client.UpdateComplianceProfile(ctx, mailafrica.UpdateComplianceProfileRequest{
	PDPCRegistered:        boolPtr(true),
	PDPCCertificateNumber: strPtr("PDPC/2024/001"),
	DefaultRetentionDays:  intPtr(30),
})

// Export a compliance audit summary
export, err := client.GetAuditExport(ctx)
fmt.Println("messages:", export.MessageCount, "addresses:", export.AddressCount)

// List agent configs across addresses
configs, err := client.ListAgentConfigs(ctx)

// Get the config for one address
config, err := client.GetAgentConfig(ctx, addr.ID)

// Set mode, persona, and where replies come from
config, err = client.UpdateAgentConfig(ctx, addr.ID, mailafrica.UpdateAgentConfigRequest{
	Mode:              "draft", // "off" | "draft" | "auto"
	Enabled:           boolPtr(true),
	Persona:           strPtr("You are a helpful support agent."),
	ReplyFromDomainID: int64Ptr(7),
	ReplyFromAddress:  strPtr("support@example.com"),
})

// Generate a one-off reply draft (respects mode; never sends)
draft, err := client.GenerateAgentDraft(ctx, addr.ID, mailafrica.AgentDraftRequest{
	Subject: "Re: Order #482",
	Body:    "Where is my order?",
})
fmt.Println(draft.Draft)

// Create an API key; the plaintext key is shown only once
keyResp, err := client.CreateAPIKey(ctx, mailafrica.CreateAPIKeyRequest{
	Name:      "CLI Key",
	Scopes:    "send,read",
	ExpiresAt: timePtr(time.Now().Add(365 * 24 * time.Hour)), // optional
})
fmt.Println("store this once:", keyResp.Key)

// List API keys
keys, err := client.ListAPIKeys(ctx)

// Revoke an API key
err = client.RevokeAPIKey(ctx, keyResp.APIKey.ID)

_, err := client.SendEmail(ctx, req)
if err != nil {
	var apiErr *mailafrica.APIError
	if errors.As(err, &apiErr) {
		fmt.Println("code:", apiErr.Code)
		fmt.Println("status:", apiErr.HTTPStatus)
		fmt.Println("request_id:", apiErr.RequestID)
	}

	if mailafrica.IsInsufficientBalance(err) {
		// top up, then retry
	}
	if mailafrica.IsRateLimited(err) {
		// back off exponentially and retry
	}
}

emails, pagination, err := client.ListSentEmails(ctx, mailafrica.ListOpts{
	Page:    1,
	PerPage: 25,
})
fmt.Println("total:", pagination.Total, "pages:", pagination.TotalPages)

client := mailafrica.New(mailafrica.Config{
	BaseURL: "https://api.mailafrica.online",
	APIKey:  os.Getenv("MAIL_API_KEY"),
	Hooks: &mailafrica.Hooks{
		OnRequest: func(req *http.Request) {
			log.Println("request:", req.Method, req.URL)
		},
		OnResponse: func(resp *http.Response, d time.Duration) {
			log.Println("response:", resp.StatusCode, d)
		},
		OnError: func(err error) {
			log.Println("error:", err)
		},
	},
})