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.
Add an identity
- Name
identityType- Type
- string
- Description
Required:
DomainorEmail, written so.
- Name
identity- Type
- string
- Description
Required: the domain, such as
example.com, or the address, such asorders@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,
sendingModeOBLIC: 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 aDomain. This mode requires Oblic's sending domain to be configured; otherwise the address is refused withPUBLIC_MAILBOX_DOMAIN. - Oblic's own domains are no account's identity.
verificationStatus is SUCCESS once an identity can send, and PENDING until then.
| Refused | cd | When |
|---|---|---|
| 400 | INVALID_IDENTITY | An Email identity that is not an address, or a domain's email that is not on it |
| 400 | PUBLIC_MAILBOX_DOMAIN | A public mailbox's domain, such as gmail.com, as a Domain, or a public-mailbox Email when Oblic's sending domain is not configured |
| 400 | OBLIC_DOMAIN | One of Oblic's own domains |
| 400 | IDENTITY_LIMIT_REACHED | The email provider holds as many identities as it allows |
| 503 | EMAIL_PROVIDER_UNAVAILABLE | The email provider could not be reached; try again |
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 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.