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

  1. In AWS, create an IAM user with the policy from GET /api/v1/settings/email/ses/policies (send; add setup if the CRM should connect the bounce reports for you) and create an access key for it.
  2. Verify your sender domain under Identities in the SES console, in the region you will use, and add its DKIM records to your DNS.
  3. Save the key: PUT /api/v1/settings/email/ses with accessKeyId, secretAccessKey, region and fromAddress. The secret is stored encrypted and never shown again.
  4. Check it: POST /api/v1/settings/email/ses:check answers 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.
  5. Connect bounce reports: POST /api/v1/settings/email/ses:connectEvents creates 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:

CheckWhy
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 domainGmail and Yahoo require both of bulk senders.
DKIMProves 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 addressIt 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 or PUT /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}:resendFailed leaves those out (and works only on a sending or sent campaign); GET /api/v1/campaigns/{id}/failed-recipients lists them with uncertain: true, and POST …/failed-recipients/{recordId}:resend sends 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-webhook verificationKey to refuse reports it didn't sign.
  • Find and fix bad addresses. The "Has bounced" filter (contacts, segments: {"type": "bounce", "kind": "hard", "withinDays": 90}, kind hard, soft or any) 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).

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.

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.

  1. In Settings → Email → Your own link domain, enter a subdomain you don't use for anything else, for example link.yourshop.com.
  2. 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).
  3. 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.