# E-mail senders

Source: https://parasend.com/docs/api/email-senders

## Endpoints

- [List e-mail senders](https://parasend.com/docs/api/email-senders/list.md): `GET /v1/email_senders`
- [Retrieve an e-mail sender](https://parasend.com/docs/api/email-senders/retrieve.md): `GET /v1/email_senders/{id}`
- [Check an e-mail sender's DNS now](https://parasend.com/docs/api/email-senders/check.md): `POST /v1/email_senders/{id}/check`
- [List the addresses Parasend sends from](https://parasend.com/docs/api/email-senders/egress-ips.md): `GET /v1/email_senders/egress_ips`

## The EmailSender object

- `id` (string, required): The sender's ID, es_ followed by 26 characters.
- `object` (string, required): Always `email_sender`.
- `mode` (string, required): One of: `parasend_domain`, `smtp`.
- `from_address` (string · email, required)
- `domain` (string, required)
- `mail_from_domain` (string, required)
- `state` (string, required): One of: `pending_dns`, `verifying`, `active`, `degraded`, `failed`, `removed`.
- `reason` (string · nullable, required): Why it waits, is degraded or failed, as a code; null when it is active. Setting up: ownership_not_found, lookup_failed, dkim_pending, mail_from_pending, dmarc_missing, retrying. Not possible: claimed_elsewhere (another organisation has the domain), identity_elsewhere (Parasend's e-mail service has the domain from elsewhere: contact Parasend), senders_off. Failed: dkim_failed, mail_from_failed, verification_timeout (records not seen within 72 hours), dkim_not_verified, mail_from_not_verified, paused_by_ses, identity_missing, identity_not_verified, tenant_not_ready. A sender that sends through your own mail server (mode smtp) also has smtp_not_configured, awaiting_test, awaiting_confirmation and smtp_secrets_off while it is set up, and when degraded the server's failure: smtp_auth_failed, smtp_app_password_required, smtp_tls_failed, smtp_rejected, smtp_oauth_failed, smtp_host_not_public, smtp_secret_missing, or, for a server that stayed down, smtp_unreachable, smtp_busy, smtp_host_unresolvable (checked again every 15 minutes).
- `records` (array of object, required): Ownership, DKIM ×3 (once known), the MAIL FROM's MX and SPF, DMARC — expected and seen.
  - `records[].record` (string, required): Which record this is. spf is the domain's own SPF record, for a sender that sends through your own mail server. One of: `ownership`, `dkim`, `mail_from_mx`, `mail_from_spf`, `spf`, `dmarc`.
  - `records[].type` (string, required): One of: `TXT`, `CNAME`, `MX`.
  - `records[].name` (string, required): The DNS name to publish at.
  - `records[].value` (string, required): What it should hold (for dmarc a suggestion: any DMARC policy counts).
  - `records[].seen` (array of string, required): What the last check found there.
  - `records[].ok` (boolean, required)
  - `records[].via` (string, optional): Ownership proved by a parent domain this organisation verified. One of: `parent_domain`.
  - `records[].advisory` (boolean, optional): Advice for the chosen mail service (an SMTP sender's spf and dmarc rows): shown to help, never required.
  - `records[].guide` (string, optional): How to word an SMTP sender's spf or dkim row: spf_add (value is the entry to add to the domain's one SPF record), spf_provider (value empty: the mail service has it), dkim_google or dkim_microsoft (value empty: the mail service makes the key). One of: `spf_add`, `spf_provider`, `dkim_google`, `dkim_microsoft`.
- `dkim_pending` (boolean, required): The DKIM records are not known yet (they come once ownership is seen).
- `used_by` (object, required)
  - `used_by.brand_profiles` (integer, required): Profiles in use whose current version names it (a count).
- `verified_at` (string · date-time · nullable, required): When ownership was first seen: from then the domain is this organisation's sender.
- `active_since` (string · date-time · nullable, required)
- `degraded_since` (string · date-time · nullable, required)
- `failed_at` (string · date-time · nullable, required)
- `last_checked_at` (string · date-time · nullable, required)
- `created_at` (string · date-time, required)
- `removed_at` (string · date-time · nullable, required)
- `smtp` (object · nullable, optional): Mode smtp only: the mail server Parasend sends through; null until it is saved. Never includes the secret.
- `last_test` (object · nullable, optional): Mode smtp only: the last test e-mail and how the server answered it.
- `test_sent_at` (string · date-time · nullable, optional): Mode smtp only: when the test e-mail with the confirmation link went out.
- `confirmed_at` (string · date-time · nullable, optional): Mode smtp only: when a person confirmed the sender from the test e-mail's link.
- `on_failure` (string, optional): While the sender cannot send, notifications go from Parasend's address under the brand's name (fallback, the default), or wait for it, a day at most (hold). One of: `fallback`, `hold`.
- `held` (object · nullable, optional): The notifications waiting for this sender while it cannot send (on_failure hold); null when none is waiting.
  - `held.count` (integer, required)
  - `held.since` (string · date-time · nullable, required): When the oldest began to wait.
  - `held.until` (string · date-time · nullable, required): When the oldest goes from Parasend's address at the latest (since + 24 h).

```json
{
  "id": "es_01M6Q4ZK3H8X2VN7R5T9W1YB3C",
  "object": "email_sender",
  "mode": "parasend_domain",
  "from_address": "tilkynningar@fyrirtaeki.example",
  "domain": "fyrirtaeki.example",
  "mail_from_domain": "mail.fyrirtaeki.example",
  "state": "active",
  "reason": null,
  "records": [
    {
      "record": "ownership",
      "type": "TXT",
      "name": "_parasend-verification.fyrirtaeki.example",
      "value": "parasend-verification=parasend-verify-5f2c9a1e7b",
      "seen": [
        "parasend-verification=parasend-verify-5f2c9a1e7b"
      ],
      "ok": true
    },
    {
      "record": "dkim",
      "type": "CNAME",
      "name": "k3v7q2m9x4p8w1z6._domainkey.fyrirtaeki.example",
      "value": "k3v7q2m9x4p8w1z6.dkim.amazonses.com",
      "seen": [
        "k3v7q2m9x4p8w1z6.dkim.amazonses.com"
      ],
      "ok": true
    },
    {
      "record": "dkim",
      "type": "CNAME",
      "name": "b5n2r8t4y7u1i9o3._domainkey.fyrirtaeki.example",
      "value": "b5n2r8t4y7u1i9o3.dkim.amazonses.com",
      "seen": [
        "b5n2r8t4y7u1i9o3.dkim.amazonses.com"
      ],
      "ok": true
    },
    {
      "record": "dkim",
      "type": "CNAME",
      "name": "h6j2l8c4v9b1n5m7._domainkey.fyrirtaeki.example",
      "value": "h6j2l8c4v9b1n5m7.dkim.amazonses.com",
      "seen": [
        "h6j2l8c4v9b1n5m7.dkim.amazonses.com"
      ],
      "ok": true
    },
    {
      "record": "mail_from_mx",
      "type": "MX",
      "name": "mail.fyrirtaeki.example",
      "value": "10 feedback-smtp.eu-west-1.amazonses.com",
      "seen": [
        "10 feedback-smtp.eu-west-1.amazonses.com"
      ],
      "ok": true
    },
    {
      "record": "mail_from_spf",
      "type": "TXT",
      "name": "mail.fyrirtaeki.example",
      "value": "v=spf1 include:amazonses.com ~all",
      "seen": [
        "v=spf1 include:amazonses.com ~all"
      ],
      "ok": true
    },
    {
      "record": "dmarc",
      "type": "TXT",
      "name": "_dmarc.fyrirtaeki.example",
      "value": "v=DMARC1; p=none;",
      "seen": [
        "v=DMARC1; p=none"
      ],
      "ok": true
    }
  ],
  "dkim_pending": false,
  "used_by": {
    "brand_profiles": 0
  },
  "verified_at": "2026-11-07T11:34:38.958Z",
  "active_since": "2026-11-07T11:34:38.958Z",
  "degraded_since": null,
  "failed_at": null,
  "last_checked_at": "2026-11-09T11:24:38.958Z",
  "created_at": "2026-11-07T11:34:38.958Z",
  "removed_at": null,
  "on_failure": "fallback",
  "held": null
}
```