Senders

Retrieve a sending address

Read one sending address, including the DNS records the creator has to publish and the reason verification last failed. Needs sending: read.

get/senders/{sender}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/senders/{sender}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: sending:read)

Query parameters

expandstring

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.

fieldsstring

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.

Response

The sending address.

object'sender' required

Always sender.

idstring uuid required

Stable identifier.

kind'commune' | 'custom' required

commune 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_emailstring email required

The full address articles are sent from.

from_namestring nullable

The display name shown beside the address in an inbox.

reply_to_emailstring email nullable

Where replies go, when the creator wants them somewhere other than from_email.

domainstring

The domain part of the address.

local_partstring

The part before the at sign.

verification_status'provisioning' | 'pending' | 'verified' | 'failed' required

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_errorstring nullable

Why verification last failed, in a form the creator can act on. Null when it has not failed.

is_defaultboolean required

Whether this is the address the newsletter sends from unless told otherwise. Exactly one address per newsletter has this.

verified_atstring date-time nullable

When the address was first verified. Null if it never was.

last_checked_atstring date-time nullable

When Commune last looked at the DNS. Verification is re checked on a schedule, so this moves without the creator doing anything.

created_atstring date-time required

When the address was added.

updated_atstring date-time

When the row last changed.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "verification_records": [
    {
      "type": "CNAME",
      "name": "mail._domainkey.example.org"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.