Update a smtp credential

Parameters

Request

curl -X PATCH 'https://app.mailyte.com/api/v1/smtp-credentials/01JBT8XQ2M9WYC3K4F6R7S8T9V' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/smtp-credentials/01JBT8XQ2M9WYC3K4F6R7S8T9V', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.patch(
    "https://app.mailyte.com/api/v1/smtp-credentials/01JBT8XQ2M9WYC3K4F6R7S8T9V",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->patch('https://app.mailyte.com/api/v1/smtp-credentials/01JBT8XQ2M9WYC3K4F6R7S8T9V');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/smtp-credentials/01JBT8XQ2M9WYC3K4F6R7S8T9V")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Success.

• dataobject
  • objectstringsmtp_credential
  • idstring

    Unique identifier for the credential.

  • namestring

    Your label for it. Not used in authentication. Never null: `smtp_credentials.name` is NOT NULL and creation requires it.

  • usernamestring

    The SMTP AUTH username, and the credential's public identity: it is what you configure in your mail library and what delivery events are attributed to. Safe to log. Never null: the column is NOT NULL and unique, and the mail server assigns it at creation -- a credential cannot exist without one.

  • statestringactive | revoked | pending_review | provisioning | failed | deleting

    The one lifecycle answer, ordered by what stops you first. `deleting` and `failed` beat everything: a credential being torn down cannot authenticate however active it looks. `pending_review` is a marketing-stream credential awaiting approval -- provisioned, but refused at AUTH time until it is reviewed. Only `active` can send.

  • streamstringtransactional | marketing

    Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label.

  • domainobject

    The one domain this credential may send as. Always present, and `id` is always populated -- it is only `name` that some responses cannot fill.

    • idstring

      **Never null.** A credential cannot exist without a domain: `smtp_credentials.domain_id` is a NOT NULL foreign key, creation requires a `domain_id` that exists, and deleting the domain deletes the credential with it. So this is the field to key off when `name` is null -- fetch `GET /domains/{domain}` with it.

    • namestring

      **null means the domain relation was NOT LOADED for this response, so its name is unknown to us here** -- it does NOT mean the credential has no domain, which is impossible, and it is not an empty name. Only `GET /smtp-credentials` eager-loads the relation; create, update, rotate, revoke, enable and the allowlist update all build their response from the credential row alone and report null. That asymmetry is a bug on our side, recorded in the report and not yet fixed -- null is the honest reading of it rather than a cover for it. `domain.id` is correct in every response, so resolve the name from that, or re-read the credential from the list endpoint.

  • ip_allowlistobject

    Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.

    • enabledboolean
    • addressesarray<string>

      IPv4/IPv6 addresses or CIDR ranges.

  • limitsobject

    Per-credential OVERRIDES of your organization's sending tier. These mirror the cap the mail server holds for this credential and are written when it is created or updated through this API; enforcement reads the mail server's own columns, never these.

    • hourlyinteger

      Recipients per hour. **null means NONE -- no per-credential override is set. It does not mean unlimited**, and it does not mean the credential may send nothing: your organization's tier still applies underneath, and it is the thing actually enforced. A client that reads null as "no cap" and removes its own throttle is the misreading this wording exists to prevent.

    • dailyinteger

      Recipients per day. null means NONE -- no per-credential override, exactly as for `hourly`, and not unlimited.

  • tracking_enabledboolean

    Whether open and click tracking is injected into HTML sent with this credential.

  • last_used_atstring

    ISO 8601 UTC, and **this field is a MIRROR, not a meter** -- read the null accordingly. Nothing in this API writes it: SMTP AUTH happens on the mail server, and an hourly reconcile copies the timestamp across. So null has two readings and you cannot tell them apart from here. Usually it is NONE -- the mail server has never seen this credential authenticate. But it is UNKNOWN whenever the mirror has not caught up: a credential that has not finished provisioning is never asked about at all, and a credential the mail server was unreachable for is skipped until the next hourly run. **A populated value can be up to an hour behind**, and the sync only ever copies a non-null timestamp across, so it never reverts to null once set. Treat null as "no evidence of use yet" rather than as proof a credential is idle, and do not revoke on it alone. For a figure read from the mail server at request time, call `GET /smtp-credentials/{credential}/usage`.

  • expires_atstring

    ISO 8601 UTC. **null means the credential does not expire** -- NONE, no expiry is set, which is the default. **Do not read null as "expired"** and do not read it as unknown: a client that treats a null date as a past one will stop sending with a credential that works. Expiry is enforced by the mail server at AUTH time, and `state` already reflects what our mirror knows about it.

  • created_atstring

    ISO 8601 UTC.

Returned inside the standard envelope.

Errors

Every status, with what causes it and what to do, is on the error reference.