Skip to main content

Authentication

Every Mailtarget request authenticates with an API key. The API path uses the key as a bearer token. The SMTP path uses the key as the SMTP password.

API authentication​

All API requests carry an Authorization header with a bearer token.

Authorization: Bearer <api_key>

Example with cURL:

curl https://transmission.mailtarget.co/v1/layang/transmissions \
  -H "Authorization: Bearer $MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Hello", "from": { "email": "you@yourdomain.com" }, "to": [{ "email": "user@example.com" }], "bodyText": "Hello" }'

If the header is missing, malformed, or the key is invalid, the API returns 401 Unauthorized with an error object. Read Errors and Rate Limits for the response shape.

SMTP authentication​

The SMTP relay uses one fixed username and the API key as the password.

username: smtp_mt_injection
password: <api_key with Send via SMTP permission>

The same key cannot send through both API and SMTP unless it has both permission scopes attached. Read SMTP Quickstart for the connection verification step.

Permission scopes​

Each API key carries one or more permission scopes. The two scopes that matter for sending are:

  • Send via API for the /v1/layang/transmissions endpoint and other API operations.
  • Send via SMTP for the SMTP relay.

Other scopes cover read-only access for analytics, contact management, template management, and webhook configuration. Pick the smallest scope that covers the workload. Do not give a production sending key admin or read-write scope it does not need.

IP allowlisting​

Each API key supports an Allowed IPs field. When set, requests from any IP outside the list are rejected. Use this for production keys that ship from known infrastructure. Leave it empty for development keys you want to use from a laptop.

If you operate behind a NAT gateway, allowlist the gateway egress IP, not the client IP.

Key rotation​

API keys do not expire automatically. Rotate them when:

  • A team member with key access leaves.
  • A key has been logged, committed to source control, or otherwise exposed.
  • A scheduled rotation policy comes due. Most regulated customers run a quarterly rotation.

The rotation pattern that does not interrupt traffic:

  1. Create a new key with the same scope and IP allowlist.
  2. Deploy it alongside the old one.
  3. Verify traffic on the new key in the dashboard.
  4. Revoke the old key.

Do not delete the old key before verifying the new one is sending traffic.

Where to store the key​

API keys are credentials. Treat them like database passwords.

  • Store in a secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, environment variables loaded from a secrets store at runtime).
  • Do not commit to source control.
  • Do not paste into chat tools or documentation.
  • Do not embed in mobile or browser code. Mailtarget is a server-side API. Frontend usage is an exposure pattern, not a feature.

What is next​

After authentication is wired, the next concept that affects every send is Sending Domains. DNS records have to be in place before a message can leave the platform with proper SPF, DKIM, and DMARC alignment.