Add Go and Terraform code samples to the API specs

[Rabsztok]

Motivation

MT-23475 — the API docs dropdown offers
seven tabs (cURL plus six SDKs), but two shipping tools are missing from it entirely: the
Go SDK (mailtrap/mailtrap-go) and the Terraform provider
(mailtrap/terraform-provider-mailtrap). The dropdown is driven purely by each operation's
x-codeSamples list, so adding a tab means adding an entry.

The ticket AC scopes this to "every supported endpoint", which is what keeps this at 142
samples rather than 260: no sample is written against a method, attribute or resource that
does not exist.

Changes

3,659 insertions, 5 deletions (the five are the CLAUDE.md SDK repository lines moved to the
mailtrap org). No existing sample, description, base URL or operation order changes.

• CLAUDE.md: Go as sample entry 8 and Terraform as entry 9, plus the conventions for both
  (why lang: hcl, the leading lifecycle comment, the verification commands, and the rule
  that an unsupported operation gets no entry rather than a "not supported" comment).
• 122 new samples across 9 spec files: 108 Go (83% of the 130 documented operations) and
  14 Terraform (11%).

Spec file	Ops	Go	Terraform	New
sandbox.openapi.yml	30	30	6	36
email-sending.openapi.yml	27	24	3	27
contacts.openapi.yml	19	19	2	21
inbound.openapi.yml	19	0	0	0
account-management.openapi.yml	13	13	2	15
email-campaigns.openapi.yml	11	11	0	11
templates.openapi.yml	5	5	1	6
email-sending-transactional.openapi.yml	2	2	0	2
email-sending-bulk.openapi.yml	2	2	0	2
sandbox-sending.openapi.yml	2	2	0	2
Total	130	108	14	122

Never covered, deliberately: all 19 inbound operations (the SDK has no inbound support,
and the provider has no inbound resources) and the 3 tracking_opt_outs operations. Those keep
the samples they have. A provider is declarative, so it covers no sending, no campaigns, no
message inspection, and manages contact lists and fields but never contact data. Terraform samples cover only creates
(8 resource blocks) and reads backed by a real data source (6 data blocks); update, delete and
import are native resource lifecycle documented once by the provider, so those operations get no
Terraform tab (review feedback).

Conventions

• Go samples are complete package main programs. That is not decoration — it is what makes
  them compile-checkable, which is the whole quality argument here. Token from
  os.Getenv("MAILTRAP_API_TOKEN") (the idiom in all of the SDK's own examples; note it diverges
  from the sibling tabs' literal YOUR_API_KEY), context.Background() inline, response
  discarded as _, log.Fatal on error, mailtrap.Ptr for optional pointer fields, exported
  constants over string literals. Written against v0.3.0, the latest release, so go get
  gives a reader exactly what the sample compiles against.
• Terraform samples use lang: hcl with label: Terraform. GitBook highlights with Prism,
  which has an hcl component and no terraform one; lang resolves through Prism identifiers
  rather than GitBook's documented linguist list, as the existing csharp and shell samples
  already demonstrate. The tab is titled by label, so it reads "Terraform" regardless.
  An HCL block is not an API call, so every sample opens with a comment naming the lifecycle
  command that fires the endpoint (# terraform apply creates the domain: POST /api/domains); create
  samples add a second comment linking the provider docs on the registry,
  where the lifecycle operations live. Each sample is self-contained down to required_providers —
  that tab is where a reader learns the source string.
• Attribute names come from the provider schema, not its published examples, which are stale
  in two places: the resource is mailtrap_domain (renamed from mailtrap_sending_domain), and
  every email_sending webhook sets the sending_stream the API requires. The samples also
  carry the provider's real footguns as comments (no update path on mailtrap_api_token, no
  secret after an import, a template body that cannot be cleared).

Merge order — two preconditions

1. Add SDK code samples to email campaigns endpoints #54 (campaigns-sdk-samples) should merge first. It adds the six other languages to the
   very same 11 x-codeSamples lists in email-campaigns.openapi.yml. Once it lands, this
   branch rebases onto it and the last commit (8667411) is the only one that needs resolving —
   or it can be dropped and redone. Nothing on Add SDK code samples to email campaigns endpoints #54's branch was touched.
2. The provider must be on the Terraform and OpenTofu registries before this merges. The
   Terraform samples are written against the real published form (source = "mailtrap/mailtrap"
   in a plain required_providers block) with no dev_overrides workaround and no "not yet
   published" caveat, on the understanding that mailtrap/terraform-provider-mailtrap is
   published ahead of this. Merging before that ships a config that does not terraform init.

How to test

CI runs Spectral, which is the only automated gate in this repo. The other two checks are local
and are the ones that catch real bugs, so they were run on the samples extracted back out of
the committed YAML, not on drafts.

• Spectral (same command as CI): npx -y @stoplight/spectral-cli lint "specs/*.openapi.yml" --verbose
  → "No results with a severity of 'error' found!"
• Go compiles. Every lang: go sample extracted to its own package against
  github.com/mailtrap/mailtrap-go@v0.3.0: 108 packages, gofmt -l empty, go vet ./...
  clean, go build ./... clean. This caught a real defect — an email-logs filter operator
  of eq where the API takes equal.
• HCL parses, formats and validates. Every lang: hcl sample extracted to its own
  config: 34 configs at the time (the 14 kept are a subset; the later cut only added a comment line), fmt -check -diff clean, and validate against a provider binary
  built from terraform-provider-mailtrap's origin/main under dev_overrides — the only
  mechanical check on attribute names. All 34 validate. (validate was originally run with
  the OpenTofu CLI; the two CLIs are drop-in for fmt/validate here, and the label
  rename touched only comments, so terraform fmt -check was re-run on all 34 after it.)
• Spectral re-run after both formatting passes, since gofmt tabs live inside source: |
  block scalars. Tabs are legal in block-scalar content; the round-trip through
  extract → gofmt -l is the proof.
• Sample ordering asserted programmatically: go is always the second-to-last entry when
  hcl follows, hcl is always last, no duplicate langs.
• Rendered docs Test in QA gitbook. Open a templates operation on docs.mailtrap.io/developers
  and confirm the dropdown reads cURL, Node.js, PHP, Python, Ruby, .NET, Java, Go,
  Terraform, that Go is highlighted, and that Terraform renders. If hcl turns out
  unhighlighted the tab still appears — accept that rather than switching to
  lang: terraform, which Prism does not know either.

Images

Worth a reviewer's eye

• Go lands on five operations the other SDKs still skip: updateDomain, the three
  company_info operations, and createSuppression currently have only shell (+ruby).
  Those tabs will read cURL / Ruby / Go until the other five languages are back-filled, which
  deserves its own ticket.
• Token idiom. Go samples read MAILTRAP_API_TOKEN from the environment; the sibling tabs
  use a literal YOUR_API_KEY. That follows the SDK's house style and CLAUDE.md's
  "use environment variables for API keys", but it is a visible inconsistency inside one
  dropdown and a one-line-per-sample change if you would rather it matched.
• 14 self-contained HCL samples repeat ~10 lines of required_providers boilerplate. The
  alternative is the provider docs page, which the create samples now link to.
• Terraform was cut from 34 to 14 samples on review: the 7 updates, 8 deletes and 5
  import-style reads are gone; only creates and genuine data-source reads remain.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 636e11a4-7b7e-4f4b-ba39-9d4b85bd4a35

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[IgorDobryn]

Not sure how to document terraform for import/delete/update operations