Skip to main content
POST
AhaSend Go SDK
The AhaSend API creates one account-global contact. Access requires contacts:write. Only email is required. The API trims it and changes it to lowercase. An email address that another contact of the account already has is refused with 409. Fields:
  • status is enabled when you leave it out or send null.
  • unsubscribed: true creates the contact as unsubscribed account-wide, and sets unsubscribed_at to the current UTC time. Campaigns do not send to an unsubscribed contact.
  • attributes must use the keys and types that you defined in the dashboard, and a value cannot be null. See Attributes.
  • validation_status and last_validated_at are read-only.
The new contact is on no list, so a campaign cannot reach it yet. To add it to a list, use Add or Update a List Contact or Batch Add List Contacts. Create Contact does not read or change suppressions. This operation accepts an Idempotency-Key header. The API stores a 201, a 400 and a 409 for a duplicate contact for 24 hours, and replays them for a retry with the same key. A 409 with Idempotent-Replayed: false and Retry-After means a request with the same key is still in progress. See Idempotency.

Authorizations

Authorization
string
header
required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Headers

Idempotency-Key
string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id
string<uuid>
required

Account ID

Body

application/json

Creates an account-global contact without list membership. Writable attribute keys and types are derived from definitions managed in the dashboard. Validation metadata, membership, and activity are not writable.

email
string<email>
required

Contact email; trimmed and lowercased before persistence

first_name
string | null
last_name
string | null
status
enum<string> | null

Defaults to enabled when omitted or null

Available options:
enabled,
disabled,
blocked,
null
status_reason
string | null
unsubscribed
boolean | null

Only true creates an initial UTC unsubscription timestamp

attributes
object | null

Values are validated against dashboard-managed account attribute definitions. Attribute members cannot be null.

Response

Contact created successfully

Public contact projection. Attribute reads are legacy-safe: values can contain null, booleans, numbers, strings, arrays, or nested objects even though new writes accept only canonical dashboard-defined values.

object
enum<string>
required

Object type identifier

Available options:
contact
id
string<uuid>
required

Unique identifier for the contact

created_at
string<date-time>
required

When the contact was created

updated_at
string<date-time>
required

When the contact was last updated

email
string<email>
required

Normalized contact email address

first_name
string
required
last_name
string
required
status
enum<string>
required
Available options:
enabled,
disabled,
blocked
status_reason
string
required
unsubscribed
boolean
required
unsubscribed_at
string<date-time> | null
required
attributes
object
required
validation_status
enum<string>
required
Available options:
unvalidated,
valid,
invalid,
risky,
unknown
last_validated_at
string<date-time> | null
required