Add a sending identity

Request

curl -X POST 'https://app.mailyte.com/api/v1/senders' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/senders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/senders",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/senders');

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

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/senders")
request = Net::HTTP::Post.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
  • objectstringsender
  • idstring

    Unique identifier for the sender.

  • namestring

    The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`.

  • emailstring

    The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender.

  • domainstring

    The domain NAME this address sends from, e.g. `acme.com` — not an id. A sender owns no DNS state of its own; it reads its domain's, so the full DNS picture is at `GET /domains/{domain}` and is deliberately not duplicated here. **null means UNKNOWN — the domain relation was not loaded on this path, so we did not read the name.** It NEVER means the sender has no domain: `senders.domain_id` is NOT NULL, so every sender has exactly one. Every published path loads the relation, so a null here is our omission rather than a fact about the sender.

  • verificationobject

    Whether this identity may be sent from. **No verification token appears here or anywhere else in the API** — verification reads the domain's public DNS, so there is nothing to prove ownership with. If a token-based flow is ever added, its token belongs in the response to the request that mints it and nowhere else: a token that claims an address is a credential, and one returned on a GET is readable by anyone who can replay the request.

    • statestringpending | verified | failed

      The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run.

    • verified_atstring

      When the last SUCCESSFUL check ran. **null means NOT INCLUDED — it is withheld whenever `state` is not `verified`**, and that is the one place in this section where a null is a deliberate withholding rather than an absence. The stored column is NOT cleared when a later check fails, so a sender that verified in March and broke its SPF in April still carries the March date; publishing it beside `state: "failed"` would be two fields giving two answers. So null here does not mean this sender never verified — it means it is not verified NOW, and any earlier success is deliberately not published. Read `state` for whether this sender works, never this field.

    • errorstring

      Why the last check failed, in words a customer can act on (typically the DNS records still missing). **null means NONE — there is no current failure to report**, which is the case whenever `state` is not `failed`. Unlike `verified_at` above, nothing is being withheld here: a successful check clears the stored error, so there is no stale string to hide.

  • created_atstring

    When this sender was created. Written on insert, so it should always be present. **null means UNKNOWN — the stored timestamp was absent**, and we will not invent a date to fill the gap.

  • updated_atstring

    When this sender was last changed. **null means UNKNOWN — the stored timestamp was absent.** It never means "never changed": a sender that has not been touched since creation carries its creation time here.

Returned inside the standard envelope.

Errors

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