Email sending
Every organisation sends through its own email provider, set up in Settings → Email: an SMTP server, SendGrid, or Amazon SES. Your sender name, your domain and your reputation stay yours.
Amazon SES
- In AWS, create an IAM user with the policy from
GET /api/v1/settings/email/ses/policies(send; addsetupif the CRM should connect the bounce reports for you) and create an access key for it. - Verify your sender domain under Identities in the SES console, in the region you will use, and add its DKIM records to your DNS.
- Save the key:
PUT /api/v1/settings/email/seswithaccessKeyId,secretAccessKey,regionandfromAddress. The secret is stored encrypted and never shown again. - Check it:
POST /api/v1/settings/email/ses:checkanswers whether the key works, the account is out of the sandbox, the domain is verified with DKIM, bounce reports are connected, and how many emails per second the account allows. - Connect bounce reports:
POST /api/v1/settings/email/ses:connectEventscreates a configuration set (codefab-crm), an SNS topic and a subscription to your organisation's webhook (GET /api/v1/settings/email/ses/events-url). Permanent bounces and spam complaints then put the address on your suppression list.
Sending speed
PUT /api/v1/settings/email/speed with {"maxPerSecond": 14} keeps every email to your provider's limit (the SES check sets it to the account's). If a provider still says "too fast", the email is not failed: campaigns and automations send it again shortly, and a direct send answers 429 send_rate_limited.
Before a big send
GET /api/v1/campaigns/{id}/send-check (the wizard shows it too) checks the campaign's From address:
| Check | Why |
|---|---|
Not a free address (freemail) | Mailbox providers refuse bulk email from gmail.com, outlook.com and the like. A campaign from one is refused (409 freemail_sender). |
| SPF and DMARC on the domain | Gmail and Yahoo require both of bulk senders. |
| DKIM | Proves the email wasn't changed on the way (unknown when it can't be told from outside). |
Bounce reports (deliveryReports) | Without them, addresses that don't work are mailed again and again. |
| Postal address | It goes at the bottom of every marketing email (Settings → Team → Organisation). |
Plain SMTP reports no bounces: an email campaign to more than 1,000 people through it needs
{"confirmWithoutBounceReports": true} on POST /api/v1/campaigns/{id}:schedule
(409 no_bounce_reports otherwise). For big lists, use Amazon SES or SendGrid with bounce reports.
Warm-up
A sending domain that hasn't sent much may send 1,000 marketing emails on its first day, then twice its
best day of the last two weeks. That reaches 25,000 in about six days, instead of a whole list landing in
spam on day one. The campaign waits for the next morning (waitingReason: "warm_up") and carries on by itself;
GET /api/v1/limits shows it as warm_up with the domain as scope. Receipts are never held back.
Ask Code F to turn it off if your domain already sends a lot through another tool.
During and after a send
- Pauses by itself. The reason is in
lastError. It pauses when the sending account refuses (a bad login, a suspended account, an unverified sender), when the provider can't be reached for 30 minutes, after 25 refusals in a row, when more than your bounce limit bounce for good (default 10%, set 5–20% in Settings → Email orPUT /api/v1/settings/bounce-limit, judged once 50 have gone out), or when more than 0.1% mark it as spam once 200 have gone out. The campaign page shows the bounce rate while it sends, and warns from half the limit. Resume it when it's fixed: nobody was skipped. - Never twice. An email the provider may have accepted (the server stopped mid-send, or no answer
came back) is never sent again by itself.
POST /api/v1/campaigns/{id}:resendFailedleaves those out (and works only on asendingorsentcampaign);GET /api/v1/campaigns/{id}/failed-recipientslists them withuncertain: true, andPOST …/failed-recipients/{recordId}:resendsends one on purpose. - People, not machines. Opens by Apple's privacy proxy and clicks by link scanners (several links
within seconds, or a known scanner) are counted apart (
machineOpened,machineClicks). Only a person's click counts as a click, moves an automation on, or picks an A/B winner. A link keeps working after the tracking window; the click just isn't counted. - Bounces and complaints reported by SES or SendGrid show on the campaign (
bounced,complained,bounceRate) and suppress the address. Each bounce keeps its reason, in the receiving server's words (550 5.1.1 user unknown): on the recipient (bounceReason), on the contact's timeline (email.bounced) and on the suppression list. A temporary bounce (mailbox full, server busy:softBouncedAt,softBounced) is only remembered; the address can still be mailed. With SendGrid, save its signed-webhookverificationKeyto refuse reports it didn't sign. - Find and fix bad addresses. The "Has bounced" filter (contacts, segments:
{"type": "bounce", "kind": "hard", "withinDays": 90},kindhard,softorany) finds everyone whose current address bounced. Fix a typo and they drop out.
Who got it, and who clicked what
GET /api/v1/campaigns/{id}/recipients lists everyone the campaign was for, 50 at a time
(limit up to 500, offset), with what each person did: sentAt, openedAt, clickedAt,
bouncedAt, complainedAt, unsubscribed and clickedLinks (the words of each link or button
they clicked), and for bounces softBouncedAt and bounceReason. Narrow it with show (sent,
opened, clicked, not_opened, bounced, soft_bounced, complained, unsubscribed, failed,
skipped, pending), search names and addresses with q,
and keep only those who clicked one link with link. GET …/recipients.csv takes the same
parameters and returns the list as CSV.
GET /api/v1/campaigns/{id}/links counts the people and clicks per link. Each link is told apart by
its place in the email and its words, so two buttons to the same page count separately (index,
label, url). Opens and clicks are people's, as in the stats: scanners and machine opens are left
out.
Your name, address and phone
Every marketing email ends with your organisation's name, postal address and phone number (as a
number you can tap). Set them in Settings → Team → Organisation, or with
PUT /api/v1/settings/organisation (name, postalAddress, phone).
Tracked links in texts
Every web link in a marketing text goes out as a short tracked link on your link domain (or
crm.codefab.dev until you have one): https://link.yourshop.com/l/Ab3dE9xQ. Write the full address
in the template; it's shortened when the text is sent, and the preview shows it the way it will go
out, so the length (and the cost) you see is right. A person's click counts like an email click:
the campaign's clicks per link and who clicked, sms.clicked on the contact's timeline, and
automations waiting for it. Link previews in chat apps and scanners don't count. Transactional texts
(receipts, codes) are sent exactly as written.
Your own link domain
The links in your emails and texts can be on your own domain instead of crm.codefab.dev: tracked links, the open pixel, unsubscribe (in the email and in the header Gmail uses for its unsubscribe button), the confirmation link, form and survey links, and SMS opt-out links. People trust links on your domain more, and so do spam filters. Images stay on our address.
- In Settings → Email → Your own link domain, enter a subdomain you don't use for anything
else, for example
link.yourshop.com. - Where your domain's DNS is managed, add the one record shown: a CNAME from that name to
crm.codefab.dev. Many DNS tools ask only for the first part of the name (link). - That's all. We check every few minutes. Once the record is found we secure the connection ourselves, which usually takes a few minutes, and the domain turns Active. From then on every new email and text uses it, and until then your links keep using crm.codefab.dev.
An active domain is checked every hour. If it stops working (the record was removed, for example), your links go back to crm.codefab.dev by themselves, so no email goes out with links that don't work. It turns active again once it works. Removing the domain does the same at once. Links in emails already sent keep working only while your DNS record stays.
Through the API: GET /api/v1/settings/link-domain shows the domain, its status (dns,
securing, active, broken) and the record to add. PUT with {"domain": "link.yourshop.com"}
sets it, POST …:check checks right away, and DELETE removes it.