# Retrieve a sending address **GET /senders/{sender}** Read one sending address, including the DNS records the creator has to publish and the reason verification last failed. Creator scope. ## Servers - Production. There is no separate sandbox host. : https://api.usecommune.com (Production. There is no separate sandbox host. ) ## Authentication methods - Api key ## Parameters ### Headers - **Commune-Version** (string(date)) The contract version this request is written against, as a release date (`YYYY-MM-DD`). Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships. An unknown value answers `400` with `invalid_version`. ### Path parameters - **sender** (string(uuid)) The sending address's `id`. It has no short id. ### Query parameters - **expand** (string) Comma separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only `id` and `object`. Each operation documents the paths it accepts, and an unknown path answers `400`. Nested paths use a dot, for example `article.newsletter`. One accepted path is not a relationship. `?expand=content` on `GET /articles/{article}` adds the Markdown rendition of the body beside the HTML one. It is the same trade the parameter always offers, a fuller response for a larger one, over a property that has more than one representation rather than over a reference. - **fields** (string) Comma separated allow list of top level properties to return on each object, so a client can trim a response it does not need in full. `id` and `object` are always returned. An unknown property name answers `400`. Properties omitted by an operation, such as `content` on any article list, cannot be brought back with `fields`. A trimmed body is a subset of the schema this operation declares, and a property that schema marks required is absent when it was not asked for. That is the point of the parameter, so a client that validates responses against the schema either sends no `fields` or relaxes `required`. ## Responses ### 200 The sending address. #### Body: application/json (object) - **object** (string) Always `sender`. - **id** (string(uuid)) Stable identifier. - **newsletter** (object | null) The newsletter that sends from this address. A `Ref` unless `newsletter` is named in `?expand=`. - **kind** (string) `native` is an address Commune provisioned on a domain it owns, which works without the creator touching DNS. `custom` is an address on the creator's own domain, which does not work until they publish the records. - **from_email** (string(email)) The full address issues are sent from. - **from_name** (string | null) The display name shown beside the address in an inbox. - **reply_to_email** (string(email) | null) Where replies go, when the creator wants them somewhere other than `from_email`. - **domain** (string) The domain part of the address. - **local_part** (string) The part before the at sign. - **verification_status** (string) How far along the address is. Only `verified` can send. `provisioning` means Commune is still setting it up and the creator has nothing to do yet. - **verification_records** (array[object]) The DNS records the creator must publish. Empty for a `native` address, where Commune owns the domain and has already done it. - **verification_error** (string | null) Why verification last failed, in a form the creator can act on. Null when it has not failed. - **is_default** (boolean) Whether this is the address the newsletter sends from unless told otherwise. Exactly one address per newsletter has this. - **verified_at** (string(date-time) | null) When the address was first verified. Null if it never was. - **last_checked_at** (string(date-time) | null) When Commune last looked at the DNS. Verification is re checked on a schedule, so this moves without the creator doing anything. - **created_at** (string(date-time)) When the address was added. - **updated_at** (string(date-time)) When the row last changed. ### 400 The request was malformed: an unknown query parameter, an unparseable cursor, an unknown `expand` path, or an unrecognised `Commune-Version`. #### Body: application/json (object) - **error** (object) ### 401 No API key was presented, or the key is unknown, revoked or expired. All four answer identically, down to the wording. Saying that a key was revoked rather than never issued confirms to whoever is holding the string that it was once real, which a legitimate caller does not need and a thief should not get. #### Headers - **WWW-Authenticate** (string) The authentication scheme this API accepts. Always `Bearer realm="Commune API"`; there is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers. #### Body: application/json (object) - **error** (object) ### 403 The key is valid but is not allowed to read this. Either it carries public scope and the operation needs creator scope, or it is bound to a different newsletter than the one addressed. #### Body: application/json (object) - **error** (object) ### 404 No such resource, or the key is not allowed to know that it exists. Commune answers `404` rather than `403` where distinguishing the two would leak the existence of private content. #### Body: application/json (object) - **error** (object) ### 429 Too many requests. Back off and retry after the interval named by the `Retry-After` response header. #### Headers - **Retry-After** (integer) Seconds to wait before retrying. #### Body: application/json (object) - **error** (object) ### 500 Something failed inside Commune. The request may be retried. #### Body: application/json (object) - **error** (object) [Powered by Bump.sh](https://bump.sh)