Connections

Connections represent email domains linked to your account. They handle inbound email routing and outbound domain verification (DNS records in AWS SES: domain verification TXT, DKIM, SPF and DMARC). Connection IDs start with con_.

List connectionsGET/v1/connections

Permission: read. Returns every connection of the account, newest first, each with inboxes_count (non-deleted inboxes linked to it). This endpoint is not paginated.

01{
02  "data": [
03    { "id": "con_xxxxxxxx", "display_name": "Acme", "domain": "acme.tickos.dev", "verification_type": "inbound_only", "verification_status": "pending", "is_active": true, "inboxes_count": 2, ... }
04  ],
05  "meta": { "total": 1 }
06}

Get a connectionGET/v1/connections/{id}

Permission: read. Returns { connection } with all its fields (including dns_records, outbound_domain, outbound_verification_status and outbound_dns_records) plus inboxes_count. 404 if the connection is not in your account.

Create a connectionPOST/v1/connections

Permission: write. Returns 201 with { connection }. The connection starts with verification_status pending and is_active true. Returns 400 if display_name is missing and 409 if the domain is already used by any connection on the platform.

01curl -X POST https://api.tickos.dev/v1/connections \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{ "display_name": "Acme support", "domain": "acme.com" }'

Update a connectionPATCH/v1/connections/{id}

Permission: write. Accepts display_name (non-empty), is_active (boolean) and metadata (object; replaces the stored metadata entirely). Domain and verification status cannot be changed via PATCH. Returns { connection }; 400 on invalid values or no fields, 404 if not found.

Delete a connectionDELETE/v1/connections/{id}

Permission: admin. Permanently deletes the connection and returns { "deleted": true, "id": "..." }. Returns 409 if it still has linked (non-deleted) inboxes. If an outbound domain is configured, its identity is also removed from AWS SES (an SES failure does not block the delete).

Set up outbound domainPOST/v1/connections/{id}/outbound-domain

Permission: write. Body: { "domain": "yourdomain.com" }. Creates the domain identity in AWS SES (DKIM 2048-bit), saves it on the connection with outbound_verification_status pending, and returns the DNS records to add at your DNS provider. tickos.dev domains are not allowed (400). Returns 404 if the connection is not in your account and 409 if the domain is already used by another TickOS workspace.

01{
02  "connection": { "id": "con_xxxxxxxx", "outbound_domain": "acme.com", "outbound_verification_status": "pending", ... },
03  "dns_records": {
04    "verification_record": { "name": "_amazonses.acme.com", "type": "TXT", "value": "..." },
05    "dkim_records": [
06      { "name": "abc123._domainkey.acme.com", "type": "CNAME", "value": "abc123.dkim.amazonses.com" }
07    ],
08    "spf_record": { "name": "acme.com", "type": "TXT", "value": "v=spf1 include:amazonses.com ~all" },
09    "dmarc_record": { "name": "_dmarc.acme.com", "type": "TXT", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com; pct=100; adkim=r; aspf=r" }
10  }
11}

Add every record: the SES domain verification TXT record (verification_record), the DKIM CNAME records (usually three), SPF and DMARC. The same records are stored in connection.outbound_dns_records, so you can read them again later with GET /v1/connections/{id}.

Verify DNS recordsPOST/v1/connections/{id}/verify-outbound

Permission: read. Checks the domain in AWS SES, updates outbound_verification_status on the connection (and outbound_verified_at the first time it is verified) and returns { connection, verification_status, ses_status }. Returns 400 if the connection has no outbound domain and 404 if it is not in your account.

• verified -- SES reports the domain verified for sending and DKIM status SUCCESS.
• failed -- SES reports verification or DKIM as FAILED.
• pending -- anything else (DNS not propagated yet, temporary failure, not started).
• ses_status -- raw SES result: { domain, verification_status, dkim_status, dkim_tokens } where the statuses are PENDING, SUCCESS, FAILED, TEMPORARY_FAILURE or NOT_STARTED.

Email DNS instructionsPOST/v1/connections/{id}/send-dns-instructions

Permission: write. Emails the outbound DNS records of the connection, with setup instructions, to someone else (for example the person who manages the DNS). The email is sent from no-reply@tickos.dev with your brand name as the sender name. By default it uses your account name and logo; send branding to white-label it.

01curl -X POST https://api.tickos.dev/v1/connections/con_xxxxxxxx/send-dns-instructions \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{
05    "email": "it@acme.com",
06    "branding": { "brand_name": "Acme", "primary_color": "#2D84C7", "support_email": "help@acme.com" }
07  }'

01{
02  "message": "DNS instructions sent successfully",
03  "message_id": "..."
04}

Returns 400 if email is invalid, branding is not an object, primary_color is not a hex color, support_email is invalid, or the connection has no outbound domain set up yet (call outbound-domain first). Returns 404 if the connection is not in your account and 500 if the email could not be sent.