SEsendfox
Contacts

Create a new contact

Changed on

Creates the contact, or updates the existing one when the address is already in the account. An existing contact keeps its status: this endpoint never resubscribes anyone. Check created and subscription_status in the response to tell the cases apart without a lookup first.

A contact you deleted is restored with its history and returned with created: false.

To tag the contact, use contact_tags. The older tags parameter on this endpoint is an alias for lists: it adds the contact to lists, not tags.

post/contacts

Request

  • Base URL
    https://api.sendfox.com
  • Auth
    OAuth 2
    Authorization codehttps://sendfox.com/oauth/authorize
    Token URLhttps://sendfox.com/oauth/token

Request body

emailstring email required
first_namestring
last_namestring
ip_addressstring
listsinteger[]

Array of list IDs to add the contact to

tagsinteger[]

Legacy alias for lists. These are list IDs, not contact tag IDs. Use contact_tags to tag a contact.

contact_tagsinteger[]

IDs of contact tags (see /contact-tags) to add, up to 100. Applies to existing and unsubscribed contacts too; a tag the contact already has is left alone. An ID the account doesn't own returns 400 and nothing is written.

resubscribeboolean

Set only when this person just asked to rejoin, such as on your own signup form. Never set it on a sync or import. If they unsubscribed from your account or from one of the given lists, they get a consent email and stay unsubscribed until they confirm it. Confirming covers your account-wide opt-out and the given lists, not other lists they left. Someone unsubscribed from your account joins the given lists only when they confirm. Limited to one email per contact every 30 days and 100 per account per day. When this is true, ip_address must be a valid IP address. Without this flag, an unsubscribed contact stays unsubscribed and no email is sent.

Response

The contact, new or existing. created says which. The resubscribe_confirmation fields appear only when resubscribe was true.

idinteger
emailstring email required
first_namestring
last_namestring
ip_addressstring
unsubscribed_atstring date-time nullable
bounced_atstring date-time nullable

When this address hard bounced. A hard bounce also sets unsubscribed_at. If unsubscribed_at is null, or far from this date, the bounce isn't what's stopping their email; they were resubscribed or opted out separately.

bounce_paused_atstring date-time nullable

When this contact was last paused for repeated bounces. Can remain set after the pause has ended; read bounce_paused_until to tell.

bounce_paused_untilstring date-time nullable

When the current repeated-bounce pause ends. Null if the contact isn't paused, or has since unsubscribed or become invalid, since no retry is coming.

invalid_atstring date-time nullable

When this address was found to be invalid. It isn't mailed while this is set.

created_atstring date-time
updated_atstring date-time
createdboolean

True only when this request added a new contact. False for an existing or restored contact.

subscription_status'subscribed' | 'unconfirmed' | 'bounce_paused' | 'unsubscribed' | 'bounced' | 'invalid'

Account-wide status after this request. unconfirmed means the account requires double opt-in and campaigns skip this contact until they answer the confirmation email. bounce_paused means repeated bounces paused them for now; they're retried when the pause ends. bounced means a hard bounce unsubscribed them. A list-only unsubscribe doesn't change this value; see /lists/{list_id}/unsubscribes.

resubscribe_confirmation_sentboolean

Whether a consent email was sent. The contact is unchanged until they confirm it.

resubscribe_confirmation_reason'not_opted_out' | 'account_not_eligible' | 'contact_deleted' | 'invalid_address' | 'bounced' | 'spam_complaint' | 'blocked_address' | 'recently_requested' | 'daily_limit_reached' | 'null' nullable

Why no email was sent. Null when one was.

Changes

  • ae5d5ba1d502Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added subschema #2 to the response body allOf list for the response status

    • info

      added the non-success response with the status