Send and receive on your own domain

At the end of this guide customers write to an address at your domain, and your replies leave from that address, signed as your domain.

What you need first

• To be an owner of the workspace. Only owners manage domains and addresses.
• Access to the DNS settings of the domain.
• A free domain slot on your plan: 5 on Lite, 10 on Pro, 25 on Business.
• For the API requests: an API token with the write ability.

Decide how mail will arrive

Sending is the same either way. Receiving has two methods, and you choose per address.

Steps

1. Add the domain. In the dashboard open Settings → Emails → Domains and click Add Domain. Over the API:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "domain": "support.example.com" }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/domains

   The response holds the domain's id, its verification_token and the DNS records.

2. Read the DNS records. The domain's page in the dashboard lists them. Over the API:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/domains/DOMAIN_ID/dns-records

   The answer is grouped by what each record is for. The names and values below are examples; copy yours from the response.

   {
     "data": {
       "sending_dns_records": [
         { "type": "CNAME", "name": "abc123._domainkey.support.example.com", "value": "abc123.dkim.amazonses.com", "purpose": "dkim" },
         { "type": "MX", "name": "bounce.support.example.com", "value": "10 feedback-smtp.REGION.amazonses.com", "purpose": "mail-from" },
         { "type": "TXT", "name": "bounce.support.example.com", "value": "v=spf1 include:amazonses.com ~all", "purpose": "spf" }
       ],
       "receiving_dns_records": [
         { "type": "MX", "name": "support.example.com", "value": "10 inbound-smtp.REGION.amazonaws.com", "purpose": "inbound" }
       ],
       "dmarc_dns_record": {
         "type": "TXT", "name": "_dmarc.support.example.com", "value": "v=DMARC1; p=none; ...", "purpose": "dmarc", "valid": false
       }
     }
   }

3. Publish the records at your DNS provider.

   Record	Type	Needed for	What it does
   DKIM (dkim)	CNAME, one per key	Sending	Signs your mail as your domain.
   Bounce address (mail-from, spf)	MX and TXT on bounce. your domain	Sending	Lets delivery reports come back and makes SPF line up with your domain.
   Receiving (inbound)	MX on the domain itself	Receiving by MX only	Delivers the domain's mail to PimiDesk.
   DMARC (dmarc)	TXT on _dmarc. your domain	Recommended	Publishes a policy. Mail from a domain with no DMARC policy can fail checks at large mail providers even when it is signed correctly. If you already have a DMARC record, keep it.
   Ownership	TXT on the domain itself	Proving the domain is yours	The value is gopimi-verification= followed by the domain's verification_token.

4. Verify ownership. Click Verify Ownership on the domain's page, or:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/domains/DOMAIN_ID/verify-ownership

   A 200 answer has ownership_verified_at set. A 422 says whether the record was not found or DNS could not be looked up just then.

5. Check the sending and receiving records. PimiDesk keeps checking by itself after you add the domain. DNS changes can take up to 72 hours to be seen. To check now, click Re-check or:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/domains/DOMAIN_ID/verify

   Read three fields in the answer: send_verified (the sending records are in place), mx_verified (the receiving record points at PimiDesk) and dmarc_dns_record.valid (a DMARC record is published).

6. Add an address that receives by MX. This needs mx_verified to be true. In the dashboard: Settings → Emails → Add Email, receive method MX Records.

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "[email protected]",
       "purpose": "ticket",
       "receive_method": "mx",
       "sender_name": "Example Support"
     }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails

   purpose decides whether mail becomes tickets or goes to an inbox: see the inbox guide.

7. Or add an address that receives by forwarding. First prove you can read the mailbox. This emails a six-character code to it, good for 15 minutes:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "email": "[email protected]" }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails/send-verification

   Then create the address with the code:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "[email protected]",
       "purpose": "ticket",
       "receive_method": "forwarding",
       "code": "123456"
     }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails

   The answer includes a forwarding_address. Set your mail provider to forward the mailbox to it. PimiDesk reads the original sender from the forwarded message, so the ticket is opened for your customer, not for your mail provider.

Check that it worked

Read the address back. can_send_resolved and can_receive_resolved should both be true:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails/EMAIL_ID

Then send an email to the address from an outside mailbox. It appears in the workspace, usually within a minute. Reply to it and look at the message you receive: the From address is yours.

What goes wrong

Next

• Choose where an address delivers its mail: tickets, shared inbox or a personal inbox
• Email pipeline: what happens to a message between arriving and showing up
• Work a ticket from open to closed