Sender identities

An email goes from one of the account's sender identities: a domain it owns, or an address. Oblic sends only from an identity that is verified. Adding and deleting identities needs a key that holds identities:manage; listing them, identities:manage or email:send.


POST/external/v1/identities

Add an identity

  • Name
    identityType
    Type
    string
    Description

    Required: Domain or Email, written so.

  • Name
    identity
    Type
    string
    Description

    Required: the domain, such as example.com, or the address, such as orders@example.com, at most 255 characters.

  • Name
    email
    Type
    string
    Description

    For a Domain, required: an address on that domain that the identity sends as.

  • Name
    displayName
    Type
    string
    Description

    Required: the name it sends as, at most 255 characters, without <, >, " or a line break.

  • Name
    replyTo
    Type
    string
    Description

    The address replies go to.

Add a domain

curl -X POST https://api.oblic.app/external/v1/identities \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityType": "Domain",
    "identity": "example.com",
    "email": "orders@example.com",
    "displayName": "Example Store"
  }'

The answer is the identity. For a domain, payload holds the DNS records to publish, each a CNAME from its key to its value: the email provider's three DKIM records, then Oblic's own.

Response, in part

{
  "status": "success",
  "data": {
    "id": "OEM000R7ZM4Q2VXH00",
    "email": "orders@example.com",
    "displayName": "Example Store",
    "domain": "example.com",
    "verificationStatus": "PENDING",
    "sendingMode": "OWN",
    "payload": [
      { "key": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw._domainkey.example.com", "value": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw.dkim.amazonses.com" },
      { "key": "pwmp4w2fqavhvhqfsxe3ch7mhc6y3kzj._domainkey.example.com", "value": "pwmp4w2fqavhvhqfsxe3ch7mhc6y3kzj.dkim.amazonses.com" },
      { "key": "y2xbgbc34rt5t5yjzu4mktqq3e4zrl7n._domainkey.example.com", "value": "y2xbgbc34rt5t5yjzu4mktqq3e4zrl7n.dkim.amazonses.com" },
      { "key": "_9f86d081884c4d659a2feaa0c55ad015.example.com", "value": "2c26b46b68ffc68ff99b453c1d304134.qwertyui.validation.oblic.app" }
    ]
  },
  "errors": null
}

Adding an identity the account has already answers with it as it is. A field with no value is left out.


Verifying it

  • A domain is verified once its DNS records are published: the DKIM records, by which the email provider signs its mail, and Oblic's own record, by which Oblic knows the domain is the account's. Every address on a verified domain can send.
  • An address gets a link from the email provider, which its owner opens. It sends once its domain is verified too, as a domain identity of the account.
  • An address at a public mailbox, such as Gmail or Outlook, can't publish records, and mail sent as one through another provider fails its checks. Oblic sends it through Oblic instead, sendingMode OBLIC: from Oblic's own sending domain, as "Your Name via Oblic", with replies going to the address. Oblic emails the address a link to confirm it is the owner's, valid for 72 hours; until it is opened, the identity can't send. A public mailbox's domain can't be added as a Domain. This mode requires Oblic's sending domain to be configured; otherwise the address is refused with PUBLIC_MAILBOX_DOMAIN.
  • Oblic's own domains are no account's identity.

verificationStatus is SUCCESS once an identity can send, and PENDING until then.

RefusedcdWhen
400INVALID_IDENTITYAn Email identity that is not an address, or a domain's email that is not on it
400PUBLIC_MAILBOX_DOMAINA public mailbox's domain, such as gmail.com, as a Domain, or a public-mailbox Email when Oblic's sending domain is not configured
400OBLIC_DOMAINOne of Oblic's own domains
400IDENTITY_LIMIT_REACHEDThe email provider holds as many identities as it allows
503EMAIL_PROVIDER_UNAVAILABLEThe email provider could not be reached; try again

GET/external/v1/identities

List identities

The account's identities, those verified before the call first. Listing also checks the pending ones again, and one that this check verifies is listed as SUCCESS in the same answer.


DELETE/external/v1/identities/{identityId}

Delete an identity

The identity stops sending, and its confirmation, for an address sent through Oblic, ends with it: added again, it is confirmed again. The answer is 200 whether or not the account had it.

Was this page helpful?